Rational Rhapsody User Guide

Before using the information in this manual, be sure to read the “Notices” section of the Help or
the PDF available from Help > List of Books.

This edition applies to IBM® Rational® Rhapsody® 7.5 and to all subsequent releases and
modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2000, 2009.

US Government Users Restricted Rights - Use, duplication, or disclosure restricted by GSA

ADP Schedule Contract with IBM Corp.

ii
 Contents

Introduction to Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Rational Rhapsody features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
UML design essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
UML diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
UML views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Diagrams in Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Specify a model with Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Development methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
The testing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Rational Rhapsody tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The Rational Rhapsody browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The Favorites browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Diagram tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Graphic editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Code generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Animator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Third-party interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Rational Rhapsody windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
View menu commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Diagram drawing area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Diagram navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Output window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Active Code View window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Welcome window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Rational Rhapsody project tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Browser filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Standard tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Edit menu commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Rational Rhapsody iii

Table of Contents

Tools for Generating and running code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Tools for managing and arranging windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Tools for the Favorites browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Tools for the VBA interface options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Tools for animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Tools for creating and editing diagram elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Tools for common annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Tools for zooming diagram views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Tools for formatting text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Tools for the layout of elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Tools for free shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Creating diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Tools for creating/opening diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Opening the main diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Locating in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Add new elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Add New > Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Add New > Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Add New > Actor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Add New > Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Add New > Use Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Add New > Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Add New > Flow Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
The Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Open the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Applying changes with the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Canceling changes on the Features window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
General tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Properties tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Pinning the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Hiding the buttons on the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Docking the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Undocking the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Opening multiple instances of the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Displaying a tab on the Features window in a stand-alone window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Docking a stand-alone window for a Features window tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Undocking a stand-alone window for a Features window tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Hiding tabs on the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Create hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Following a hyperlink. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Edit a hyperlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Deleting a hyperlink. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

iv User Guide
 Table of Contents

Hyperlink limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Create a diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Creating a diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Create a Rational Rhapsody project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Creating a Rational Rhapsody project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Import a Rational Rhapsody project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Importing a Rational Rhapsody project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Import source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Importing source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Search window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Graphic editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Call stack and event queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Classes and types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Creating a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Class features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Defining the characteristics of a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Defining the attributes of a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Class operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Primitive operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Receptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Triggered operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Destructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Define class ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Define relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Showing all relations for a class, object, or package in a diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Defining class tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Defining class properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Adding a class derivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Making a class an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Defining class behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Generating, editing, and roundtripping class code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Generating class code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Editing class code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Roundtripping class code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Opening the main diagram for a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Display option settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Rational Rhapsody v
Table of Contents

General tab display options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Displaying attributes and operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Removing or deleting a class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Partial specification of ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Creating a port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Specifying the features of a port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
The Port General tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
The Port Contract tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
The Tags tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
The Properties tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Viewing ports in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Connecting ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Using rapid ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Selecting which ports to display in the diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Creating a new port for a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Showing all ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Showing new ports only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Hiding all ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Deleting a port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Programming with the port APIs in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Port code generation in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Port code generation in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Composite types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Creating enumerated types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Creating language types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Using %s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Creating structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Creating Typedefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Creating unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Language-independent types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Changing the type mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Changing the order of types in the generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Using fixed-point variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Defining fixed-point variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Operations permitted for fixed-point variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Restrictions on use of fixed-point variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Fixed-point conversion macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

vi User Guide
 Table of Contents

Java enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Adding a Java enum to a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Defining constants for a Java enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Adding Java enums to an object model diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Creating Java enums with the Rational Rhapsody API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Template classes and generic classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Creating a template class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Using template classes as generalizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Creating an operations template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Creating a functions template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Instantiating a template class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Code generation and templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Template limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Eclipse platform integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Platform integration prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Confirming your Rational Rhapsody Platform Integration within Eclipse . . . . . . . . . . . . . . . . . 128
Rational Rhapsody Platform Integration within Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Rational Rhapsody perspectives in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Rational Rhapsody Eclipse support for add-on tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Eclipse projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Creating a new Rational Rhapsody project within Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Opening a Rational Rhapsody project in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Adding new elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Filtering out file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Exporting Eclipse source code to a Rational Rhapsody project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Importing Rational Rhapsody units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Importing source code (reverse engineering) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Search and replace in models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Accessing the Rational Rhapsody search facility in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Generate and edit code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Checking the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Generate code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Selecting Dynamic Model-Code Associativity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Edit code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Build, debug, and animate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Building your Eclipse project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Debugging your Eclipse project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Rational Rhapsody animation in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Eclipse configuration management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Rational Rhapsody vii

Table of Contents

Parallel development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Configuration management and Rational Rhapsody unit view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Sharing a Rational Rhapsody model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Performing team operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Rational Rhapsody DiffMerge facility in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Generate Rational Rhapsody reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Generating a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Rational Rhapsody properties overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Property groups and definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Parsing regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Property file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Rational Rhapsody keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Predefined variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Map custom properties to keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Rational Rhapsody properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Using the Properties tab in the Features window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
PRP files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Property inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Concepts used in properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Static architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
IncludeFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Selective framework includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Reactive classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Units of collaboration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
The Executer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Rational Rhapsody environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Format properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Defining default characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Defining line characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Rational Rhapsody projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Project elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Creating and managing projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

viii User Guide

 Table of Contents

Creating a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Opening an existing Rational Rhapsody project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Search and replace facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Locating and listing specific items in a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
File menu commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Editing and changing a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Using IDF for a Rational Rhapsody in C project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Saving a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Renaming a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Refactoring or renaming in the user code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Closing all diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Closing a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Closing Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Creating and loading backup projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Archiving a project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Table and matrix views of data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Basic method to create views from layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Creating a table layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Creating a table view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Creating a matrix layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Creating a matrix view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Setting up an initial layout for table and matrix views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Managing table or matrix data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
The Rational Rhapsody specialized editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Creating projects in Rational Rhapsody Designer for Systems Engineers . . . . . . . . . . . . . . . . . . . . . . . 237
Creating projects in Rational Rhapsody Architect for Systems Engineers . . . . . . . . . . . . . . . . . . . . . . . 239
Creating projects in Rational Rhapsody Architect for Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Components with variants for software product lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Creating variation points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Defining variants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Selecting a variant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Generating code for software variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Multiple projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Inserting an existing project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Inserting a new project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Setting the active project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Copy and reference elements among projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Moving elements among projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Closing all open projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Managing project lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Project limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Rational Rhapsody ix
Table of Contents

Naming conventions and guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Guidelines for naming model elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Standard prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Using project units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Unit characteristics and guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Separating a project into units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Modifying units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Saving individual units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Loading and unloading units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Saving packages in separate directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Using environment variables with reference units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Preventing unresolved references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Using workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Creating a custom Rational Rhapsody workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Adding units to a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Unloaded units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Opening a project with workspace information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Controlling workspace window preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Project files and directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Parallel project development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Unit types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
DiffMerge tool functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Project migration and multi-language projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Opening models from a different language version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Multi-language projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Domain-specific projects and the NetCentric profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Creating a NetCentric project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Creating a service contract to export as WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Exporting a WSDL specification file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Importing a WSDL specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Schedulability, Performance, and Time (SPT) profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Manually adding the SPT profile to your model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Using the stereotypes and tagged values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Changing the profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Rational Rhapsody with IDEs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
IDE options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Locating Rational Rhapsody elements in an IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Opening the IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Creating an IDE project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Using the Rational Rhapsody Workflow Integration with Eclipse . . . . . . . . . . . . . . . . . . . . . . . 280
Converting a Rational Rhapsody configuration to Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

x User Guide
 Table of Contents

Importing Eclipse projects into Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Creating a new Eclipse configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Troubleshooting your Eclipse installation with Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Switching between Eclipse and Wind River Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Rational Rhapsody tags for the Eclipse configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Configuring Rational Rhapsody for Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Eclipse workbench properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Editing Rational Rhapsody code using Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Locating implementation code in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Opening an existing Eclipse configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Disassociating an Eclipse project from Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Workflow integration with Eclipse limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Visual Studio IDE with Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Changing an existing Rational Rhapsody configuration to Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . 288
Adding a new Visual Studio configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Creating a new Visual Studio project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Co-debugging with Tornado. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Preparing the Tornado IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
IDE operation in Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Co-debugging with the Tornado debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
IDE properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Creating Rational Rhapsody SDL blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Model elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Browser techniques for project management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Opening the Rational Rhapsody browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Browser display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Basic browser icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Rational Rhapsody browser menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Deleting items from the Rational Rhapsody browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
The Browse From Here browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Opening a Browse From Here browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Closing a Browse From Here browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Navigating a Browse From Here browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Deleting items from the Browse From Here browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Browse From Here browser limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
The Favorites browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Favorites toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Showing and hiding the Favorites browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Creating your Favorites list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Creating a folder structure for your Favorites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Re-ordering the items on your Favorites list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Rational Rhapsody xi
Table of Contents

Removing items from your Favorites list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Favorites browser limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Adding elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Naming new elements in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Browser settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Package design guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Creating a package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Using functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Using objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Using variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Receptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Adding diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Locating an element on a diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Element identification and paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Descriptive labels for elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Setting properties for Asian languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Adding a label to an element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Removing a label from an element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Label mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Modify elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Moving elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Copying elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Renaming elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Deleting elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Editing multiple elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Re-ordering elements in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

xii User Guide

 Table of Contents

Displaying stereotypes of model elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Creating graphical elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Smart drag-and-drop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Searching in the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Finding element references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Advanced search and replace features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Using the auto replace feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Searching for elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Searching in field types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Previewing in the search and replace facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Controlled files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Creating a controlled file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Browsing to a controlled file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Controlled file features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Troubleshooting controlled files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Controlled file limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Print Rational Rhapsody diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Selecting which diagrams to print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Diagram print settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Using page breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Exporting Rational Rhapsody diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Annotations for diagrams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Creating annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Editing annotation text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Defining the features of an annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Converting notes to comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Anchoring annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Changing the display options for annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Deleting an annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Using annotations with other tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Annotation limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Creating a project without a profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Backward compatibility profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Types of profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Converting packages and profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Profile properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Use a profile to enable access to your custom help file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Stereotypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Associating stereotypes with an element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Associate a stereotype with a new term element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Rational Rhapsody xiii

Table of Contents

Re-ordering stereotypes in a list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

Associating a stereotype with a bitmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Deleting stereotypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Establishing stereotype inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Special stereotypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Use tags to add element information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Defining a stereotype tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Defining a global tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Defining a tag for an individual element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Adding a value to a tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Deleting a tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

The Internal code editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Window properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
The Color/Font tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
The Language/Tabs tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
The Keyboard tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
The Misc tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Mouse actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Using Undo and Redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Using the search feature of the internal code editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Bookmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Printing from the internal code editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

Graphic editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

Create new diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Creating new statecharts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Creating new activity diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Creating all other diagram types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Opening existing diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Navigating forward from opened diagram to opened diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Navigating backwards from opened diagram to opened diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Deleting diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Automatically populating a diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Relation type styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Creating and populating a new diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Automatically populating existing diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Property settings for the diagram editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Setting diagram fill color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

xiv User Guide

 Table of Contents

Create elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

Repetitive drawing mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Drawing boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Drawing arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Naming boxes and arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Draw freestyle shapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Placing elements using the grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Setting the grid properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Snapping to the grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Displaying the rulers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Autoscroll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Select elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Selecting elements using the mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Selecting elements using the edit menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Selection handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Selecting multiple elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Edit elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Resizing elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Moving control points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Moving elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Maintain line shape when moving or stretching elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Change the format of a single element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Copying formatting from one element to another . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Changing the format of a metaclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Making the format for an element the default formatting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Copy an element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Arranging elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Removing an element from the view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Deleting an element from the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Editing text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Display compartments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Selecting items to display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Display stereotype of items in list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Zoom. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Zoom toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Zooming in and zooming out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Refreshing the display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Scaling a diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Panning a diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Undoing a zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Specifying the specification or structured view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

Rational Rhapsody xv
Table of Contents

The Bird’s Eye (diagram navigator) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

Showing and hiding the Bird’s Eye window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Navigating to a specific area of a diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Using the Bird’s Eye to enlarge and shrink the visible area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Scrolling and zooming in drawing area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Changing the appearance of the viewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
General characteristics of the Bird’s Eye window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Complete relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Use IntelliVisor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Activating IntelliVisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
IntelliVisor information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

Customizations for Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Creating a link to a helper application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Adding a VBA macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Visual Basic for applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
VBA and Rational Rhapsody. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
The VBA project file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
VBA versus VB programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
Writing VBA macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Creating and editing macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Exporting and importing VBA macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Creating a customized profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Creating a new stereotype for the new profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Re-using your customized profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Adding new element types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
New terms and their properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Availability of out-of-the-box model elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
Creating a customized diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Adding customized diagrams to the diagrams toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Creating a customized diagram element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Adding customized diagram elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Diagram types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Diagram elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Customize the Add New menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Re-organizing the common list section of the Add New menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Re-organizing the bottom section of the Add New menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Customizing the Add New menu completely. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Re-using property changes to the Add New menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505

xvi User Guide

 Table of Contents

Creating a Rational Rhapsody plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

Writing a Java plug-in for Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Creating a .hep file for the plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Attaching a .hep file to a profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Troubleshooting Rational Rhapsody plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Debugging Rational Rhapsody plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
The simple plug-in sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

Use case diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

Use case diagrams overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
Opening an existing use case diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
Create use case diagram elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Use case diagram drawing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
System boundary box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Creating packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Creating associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Creating generalizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Creating dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

Object model diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

Object model diagrams overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Object model diagram elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Object model diagram drawing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Opening an existing object model diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Creating an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Object characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Parts in an object model diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Object features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Converting object types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Converting classes to objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Code generation for objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Editing the declaration order of objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Changing the value of an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Creating a vacuum pump model as an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Creating classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Class compartments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545

Rational Rhapsody xvii

Table of Contents

Creating composite classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546

Creating a package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Package features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Realization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Bi-directional associations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Creating a bi-directional association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Association features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Directed associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Aggregation associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Composition associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
Dependency arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
Drawing the dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Creating an actor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
The actor menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Flows and flowitems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Creating a flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
Features of a flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
Conveyed information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
Flow menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Flowitems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Embedded flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
Creating a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
Converting files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
Associations and dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
Code generation for files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
Files with other tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
Attributes, operations, variables, functions, and types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Adding details to the object model diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Flow ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
External elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Reverse engineering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
External elements created by modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
Converting external elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Implementation of the base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

xviii User Guide

 Table of Contents

Implicit invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

Explicit invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Namespace containment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618

Activity diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

Activity diagram features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Advanced features of activity diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
Activity diagram elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
Activity diagram drawing tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
Drawing an action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Modify the features of an action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Displaying an action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
Activity frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
Action blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
Subactivities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
Creating a final activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
Object nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Adding call behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Activity flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
Join or fork bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
Swimlanes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Adding calls to behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Add action pins/activity parameters to diagrams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Local termination semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
Code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Functor classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Limitations and specified behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

Flow charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

Define algorithms with flow charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Flow charts similarity to activity diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
Create flow chart elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Tools for drawing flow charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
Action blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
Activity final . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Activity flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664

Rational Rhapsody xix

Table of Contents

Code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

Flow chart limitations and specified behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

Sequence diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

Sequence diagram layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
Names pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Message pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
Analysis versus design mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
Showing unrealized messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Realizing a selected element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Creating sequence diagram elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
Sequence diagram drawing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
Creating a system border . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Creating an instance line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Creating a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
Creating a reply message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
Drawing an arrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Creating a destroy arrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Creating a condition mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Creating a timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
Creating a cancelled timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
Creating an actor line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
Specifying a time interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
Creating a dataflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
Creating a partition line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
Creating an interaction occurrence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
Creating interaction operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
Creating execution occurrences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
Shifting diagram elements with the mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Sequence diagrams in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Animation for selected classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Sequence diagram comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Sequence comparison algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Comparing sequence diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
Sequence comparison options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
The Instance Groups tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
The Message Groups tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720

Statecharts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726

xx User Guide
 Table of Contents

Opening an existing statechart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

Statechart drawing tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
Drawing a state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
State name guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
Features of states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
Display options for states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
Termination states. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Local termination code with the reusable statechart implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Local termination code with flat statechart implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
Creating a statechart transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
Features of transitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
Types of transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
Selecting a trigger transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
Transition labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
Guards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Initial connectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
Events and operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
Sending events across address spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
Properties for sending events across address spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
API for sending events across address spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
Functions for serialization/unserialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
Send action elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Defining send action elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Display options for send actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
Graphical behavior of send actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
Code generation for send actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
And lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
Drawing And lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
Connectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Decision nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
History connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
Merge nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
Diagram connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
Termination connectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
EnterExit points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Submachines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

Rational Rhapsody xxi

Table of Contents

Creating a submachine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

Opening a submachine or parent statechart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Deep transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Merging a sub-statechart into its parent statechart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766
Statechart semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
Single message run-to-completion processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
Active transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
Transition selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
Transition execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Active classes without statecharts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Single-action statecharts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Inherited statecharts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
Types of inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
Inheritance color coding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
Inheritance rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Overriding inheritance rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
Overriding textual information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
Refining the hierarchy of reactive classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
IS_IN Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
Message parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
Modeling of continuous time behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Interrupt handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Inlining of statechart code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
Tabular statecharts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
Format of statechart tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
Modifying statecharts from tabular view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788

Panel diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

Panel diagram features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
Creating a panel diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
Create panel diagram elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
Panel diagram drawing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
Drawing a bubble knob control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
Drawing a gauge control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
Drawing a meter control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
Drawing a level indicator control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
Drawing a matrix display control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
Drawing a digital display control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
Drawing an LED control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
Drawing an on/off switch control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

xxii User Guide

 Table of Contents

Drawing a push button control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804

Drawing a button array control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
Drawing a text box control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
Drawing a slider control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
Bind a control element to a model element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
Binding a control element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
More about binding a control element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
Change the settings for a control element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
Changing the settings for a control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
Change the properties for a control element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
Properties for a bubble knob control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
Properties for a gauge control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
Properties for a meter control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
Properties for a level indicator control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
Properties for a matrix display control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
Properties for a digital display control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
Properties for a LED control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
Properties for a on/off switch control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
Properties for a slider control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
Setting the value bindings for a button array control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
Changing the display name for a control element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
Panel diagram limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828

Structure diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829

Structure diagram drawing Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
Composite classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
Creating an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
Features of objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
Actual Call window for objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
Changing the order of objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
Supported Rational Rhapsody functionality in objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
Structure diagram ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
Links and associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
Dependency uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
Flows mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
External files in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836

Rational Rhapsody xxiii

Table of Contents

Collaboration diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837

Collaboration diagrams overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
Collaboration diagram tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
Classifier roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
Multiple objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
Creating an actor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
Creating a link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
Features of links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
Changing the underlying association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
Link messages and reverse link messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
Creating a link message or reverse link message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845

Component diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847

Component diagram uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
Component diagram drawing Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
Elements of a component diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
Component interfaces and realizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
Component configurations in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
Component options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
Active component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
Configuration menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
Setting the active configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
Features of configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
Using selective instrumentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
Making permanent changes to the main file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
Creating components under a package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869

Deployment diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871

Opening an existing deployment diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
Deployment diagram drawing tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872

xxiv User Guide

 Table of Contents

Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
Creating a node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
Changing the owner of a node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
Designating a CPU type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
Features of nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
Component instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
Adding a component instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
Moving a component instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
Features of component instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
Adding a dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879
Assigning a package to a deployment diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880

Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
Checker features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
The Checks tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
Specifying which checks to run. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Checking the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
Checks tab limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
User-defined checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
Creating user-defined checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
Removing user-defined checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Deploying user-defined checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888
External checks limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888
List of Rational Rhapsody checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889

Basic code generation concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909

Code generation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
The Code Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
Generating Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
Incremental Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
Smart Generation of Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
Generating Code Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
Dynamic Model-Code Associativity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
Generating Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
Stopping Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916

Rational Rhapsody xxv

Table of Contents

Building the Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916

Deleting Old Objects Before Building Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917
Running the Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
Shortcut for Creating an Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
Stopping Model Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
Generating Code for Individual Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
Using the Code Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
Using the Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
Using an Object Model Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
Results of Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
Output Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
Locating and Fixing Compilation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
Viewing and Editing the Generated Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
Setting the Scope of the Code View Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
Adding Line Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
Editing Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
Locating Model Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
Regenerating Code in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Associating Files with an Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Using an External Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
Viewing Generated Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
Deleting Redundant Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
Generating Code for Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
Selecting Actors Within a Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
Limitations on Actor Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
Generating Code for Component Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
Cross-Package Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
Class Code Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
Class Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
Implementation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
Changing the Order of Operations/Functions in Generated Code . . . . . . . . . . . . . . . . . . . . . . . 942
Using Code-Based Documentation Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
Template Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
Sample Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
Wrapping Code with #ifdef-#endif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
Overloading Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
Using Anonymous Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
Creating Anonymous Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954

xxvi User Guide

 Table of Contents

Deleting Anonymous Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955

Deleting Components of a Composite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
Using Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
To-One Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
To-Many Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
Ordered To-Many Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
Qualified To-Many Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
Random Access To-Many Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
Support for Static Architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
Properties for Static Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
Static Memory Allocation Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
Static Memory Allocation Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
Static Memory Allocation Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
Using Standard Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
Applications for Standard Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
Creating Standard Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
Statechart Serialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
Generating Methods for Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
Serialization Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
Methods Provided for Implementing Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971
Generating Classes as Structs in C++. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
Components-based Development in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
Action Language for Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
C Optimization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976

Customize C code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977

Code customization concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
Customizing code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
Viewing the simplified model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
Customize the generation of the simplified model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
Properties used for simplification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
Customizing the code writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
Customizing the C rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
Deploying the changed rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984

Reverse engineering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

Reverse engineering restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

Rational Rhapsody xxvii

Table of Contents

Reverse engineering legacy code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986

Reverse engineering tool features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
Displaying files in a tree view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
Displaying files in a flat view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
Reverse engineering messages in the Output window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
Initializing the Reverse Engineering window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
Excluding particular files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992
Analyzing makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992
Visualization of external elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
Defining preprocessor symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
Adding a preprocessing symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
Analyzing #include files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
Mapping classes to types and packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
Specifying directory structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
Specifying reference classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
Reference classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
Locating a directory that contains reference classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
Miscellaneous reverse engineering options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
Modeling classes as Rational Rhapsody types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
Reflect data members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
Reverse engineering error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
Creating flow charts during reverse engineering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
Updating existing packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
Command-line interface for populate object model diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034
Populate object model diagrams limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034
Reverse engineering message reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
Code respect and reverse engineering for Rational Rhapsody Developer for C and C++ . . . 1037
Reverse engineering for C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
Reverse engineering for Rational Rhapsody in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
Reverse engineering other constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
Unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
Enumerated types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
Limitations for comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040
Macro collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
Collected macro file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042

xxviii User Guide

 Table of Contents

Controlling macro collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042

Code generation of imported macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
Limitations for imported macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
Backward compatibility issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044
Results of reverse engineering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044
Lost constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045

Roundtripping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047
Supported elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
Roundtripping limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
Dynamic Model-code Associativity (DMCA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049
The roundtripping process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Automatic and forced roundtripping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Roundtripping classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Modifying code segments for roundtripping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051
Recovering lost roundtrip annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
Roundtripping classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053
Roundtripping packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
Roundtripping deletion of elements from the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
Roundtripping for C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058
Roundtripping for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
Roundtripping properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059

Code respect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063

Activating the code respect feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
Where code respect information is defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065
Making SourceArtifacts display in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066
Manually adding a SourceArtifact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
Reverse engineering and SourceArtifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
Roundtripping and SourceArtifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
Code generation and SourceArtifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068
Configuration management and SourceArtifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068

Code-centric mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069

Entering code-centric mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
Leaving code-centric mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070
Roundtripping in code-centric mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072
Code generation in code-centric mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073
Diagrams for which code not generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074

Rational Rhapsody xxix

Table of Contents

Code regeneration in code-centric mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074

Animation in code-centric mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
Scope for code-centric models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
Properties modified by code-centric settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077

Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
Animation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
Animation Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
Preparing for Animation - General Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
Create a Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1081
Creating a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1081
Setting the Component Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
Creating a Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083
Setting the Instrumentation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
Running the Animated Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086
Running on the Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086
Running on a Remote Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
Opening a Port Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1088
Testing an Application on a Remote Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1088
Testing a Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
Partially Animating a Model (C/C++) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
Setting Elements for Partial Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090
Partial Animation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090
Partially Animated Sequence Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
Ending an Animation Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
Animation Toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
Creating Initial Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
Break Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
Command Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
Generating Events Using the Animation Command Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
Events with Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096
Generating Events Using the Command History List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097
Threads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
Thread View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
Setting the Thread Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
Names of Threads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
Notes on Multiple Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
Active Thread Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100

xxx User Guide

 Table of Contents

Creating Breakpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101

Defining Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
Enabling and Disabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1104
Deleting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105
Event Generator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
Generating Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
Events History List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
Calling Animation Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
Scheduling and Threading Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
Using Partial Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
Scheduling and Threading Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
Animation Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
Silent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
Watch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
Viewing the Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114
Event Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114
Animated Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
Animated Sequence Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
Animating Statecharts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
Instance Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
Names of Class Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
Names of Component Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
Navigation Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
Names of Special Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
Animation Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
Sample Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
Running Scripts Automatically. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
Black-Box Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
Animation Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
Using the Properties for Black-Box Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
Instance Line Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
Behavior and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
Animation Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
If Animation and Application are Out of Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
Passing Complex Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
Combining Animation Settings in the Same Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
Animation Feature Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
Guidelines for Writing Serialization Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138

Rational Rhapsody xxxi

Table of Contents

AnimSerializeOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138
AnimUnserializeOperation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1140
Running an Animated Application Without Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . 1141

Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
Tracer Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
Starting a Trace Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144
Controlling Tracer Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
Accessing Tracer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
Tracer Commands and an Input File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
Threads in Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
Tracer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
CALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
GEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
go . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155
input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155
LogCmd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157
quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157
resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
set focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
suspend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
timestamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
watch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166
Tracer Messages by Subject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167
Ending a Trace Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169

Managing Web-enabled devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1171

Use of Web-enabled Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1171
Setting Model Elements as Web-Manageable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
Limitations on Web-Enabling Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
Selecting Elements to Expose to the Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
Connecting to the Web Site from the Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
Navigating to the Model through a Web Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
The Web GUI Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178

xxxii User Guide

 Table of Contents

Viewing and Controlling of a Model via the Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183

Customizing the Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184
Adding Web Files to a Rational Rhapsody Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184
Accessing Web Services Provided with Rational Rhapsody. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1185
Adding Rational Rhapsody Functionality to Your Web Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189
Customizing the Rational Rhapsody Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193

Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
ReporterPLUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
Launching ReporterPLUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196
ReporterPLUS templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196
Generating reports using existing templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1200
Viewing reports online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
Generating a list of specific items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
Using the system model template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
The internal reporting facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203
Producing an internal report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203
Setting the RTF character set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205
Using the internal report output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205

Java-specific issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1207

Generation of Javadoc comments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1207
Including Javadoc comments in Rational Rhapsody-generated code. . . . . . . . . . . . . . . . . . . . . . . . . . 1207
Changing the appearance of Javadoc comments in generated code . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
Enabling/disabling Javadoc comment generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
"Built-in" keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1209
Description templates in JavaDocProfile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1209
Multiple appearance of Javadoc tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1209
Adding new Javadoc tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
Javadoc handling in reverse engineering and roundtripping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
Javadoc troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
Static import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
Adding static imports to a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
Reverse engineering/roundtripping and static import statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
Code generation checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
Static blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
Adding static blocks to classes in a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
Changing a static block to an operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
Reverse engineering/roundtripping and static blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
Generating JAR files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
Java 5 annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215

Rational Rhapsody xxxiii

Table of Contents

Creating a JavaAnnotation type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215

Using a JavaAnnotation type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1216
Using a JavaAnnotation within a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217
Code generation and Java 5 annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
Reverse engineering and Java 5 annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
Limitations for Java 5 annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
Java reference model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221

Systems engineering with Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . 1223

Installing and launching systems engineering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
Creating a SysML profile project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224
SysML profile features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225
SysML profile packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
Views and viewpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
Adding elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
Harmony process and toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1230
Harmony process summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1230
Creating a Harmony project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
Harmony profile features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234
Systems engineering requirements in Rational Rhapsody. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1242
Analysis and requirements using the Rational Rhapsody Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243
Searching requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245
Creating Rational Rhapsody requirements diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245
Creating specialized requirement types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249
Requirements tabular view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1250
Creating use case diagrams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1251
Boundary box and the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1252
Actors and systems design in use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1252
Use case features for systems engineering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1253
Associating actors with use cases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1254
Defining requirements in use case diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255
Tracing requirements in use case diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255
Dependencies between requirements and use cases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255
Defining flow in a use case diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
Defining the stereotype of a dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
Activity modeling in SysML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257
Action types in SysML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257
SysML activity diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257
Creating an activity diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258
Setting activity diagram properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258
Activity diagram drawing tools for systems engineering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259

xxxiv User Guide

 Table of Contents

Drawing action states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1260

Drawing a initial flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1261
Drawing a subactivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1261
Drawing activity flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1261
Drawing activity flows between states. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
Drawing swimlanes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
Drawing a fork node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263
Drawing a join node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263
Creating a sequence diagram from an activity diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263
Creating a design structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264
Block properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264
Blocks and behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265
Creating a block definition diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265
Block definition diagram drawing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266
Adding graphics to block definition diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1268
Creating an internal block diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269
Internal block diagram drawing tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270
Drawing the parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270
Drawing standard ports and links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1271
Specifying the port contract and attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1271
Parametric diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1272
Parametric diagram drawing tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273
Creating the constraint block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274
Creating the parametric diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275
Binding constraint properties together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276
Adding equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276
Implementation using the action language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1277
Basic syntax rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1277
Frequently used statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1278
Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1278
Assignment and arithmetic operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279
Defining an action using the action language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279
Checking action language entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1280
Action language reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1281
System validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286
Creating a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286
Setting the component features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1287
Creating a configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1287
Preparing to Web-enable the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1288
Creating a Web-enabled configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1288
Selecting elements to Web-enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1290

Rational Rhapsody xxxv

Table of Contents

Connecting to the Web-enabled model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291

Navigating to the model through a Web browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291
Viewing and controlling a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292
Sending events to your model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292
Importing DoDAF diagrams from Rational System Architect . . . . . . . . . . . . . . . . . . . . . . . . . 1293
Mapping the import scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1293
Importing the Rational System Architect elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1295
Converting imported data into a Rational Rhapsody diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296
Post processing mechanism for Rational System Architect users . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297
Generating a Imported Elements report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297
Integration with Teamcenter systems engineering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1298
UML or SysML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1298
Prerequisites for working with Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1300
Importing a Rational Rhapsody model into Teamcenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1300
Creating a Rational Rhapsody model from existing Teamcenter Project . . . . . . . . . . . . . . . . . . . . . . . 1301
Modifying shared elements from within Teamcenter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1301
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302

The MicroC profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303

The extended execution model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
MicroC code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
UI changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
The mxf. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304
Modeling network ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304
Optimizations for static systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305
Direct flow ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305
Direct relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306
Monitoring of application running on target. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
Using target monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
Viewing MicroC properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309

IBM Rational Rhapsody DoDAF Add On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311

Rational Rhapsody for DoDAF Add On and profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311
DoDAF views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
Operational view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
Systems view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
Technical view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
All views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
Products included in the Rational Rhapsody for DoDAF Add On . . . . . . . . . . . . . . . . . . . . . . 1314

xxxvi User Guide

 Table of Contents

Rational Rhapsody for DoDAF Add On helper utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318

Setup DoDAF packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Create OV-2 from Mission Objective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Create OV-6c from Mission Objective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Update OV-2 from OV-6c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Generate Service Based OV-3 Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Generate SV-3 Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Generate SV-5 Summary Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Generate SV-5 Full Matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321
Rational Rhapsody for DoDAF Add On Report Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321
Rational Rhapsody project for Rational Rhapsody for DoDAF Add On configuration. . . . . . 1322
Creating a Rational Rhapsody for DoDAF project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322
Diagrams toolbar for a Rational Rhapsody for DoDAF project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
DoDAF tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1327
Generating the OV-3 Operational Information Exchange Matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329
Generating the DoDAF report from the architecture model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334
Verifying the Rational Rhapsody for DoDAF Add On installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334
Manually adding the Rational Rhapsody for DoDAF Add On helpers. . . . . . . . . . . . . . . . . . . . . . . . . . 1335
Correcting messages that appear as mission objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1337
View, caption, or table of figures is missing from document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339

IBM Rational Rhapsody MODAF Add On . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341

Rational Rhapsody for MODAF Add On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342
MODAF viewpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
All Views viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345
Strategic viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345
Operational viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345
Systems viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346
Acquisition viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346
Technical viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346
Views Included in the Rational Rhapsody for MODAF Add On . . . . . . . . . . . . . . . . . . . . . . . . 1347
Configure a Rational Rhapsody project for MODAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
Creating a Rational Rhapsody for MODAF project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
Customize the Rational Rhapsody table and matrix views for MODAF . . . . . . . . . . . . . . . . . . 1360
Creating stereotypes and using tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
About creating table/matrix views in MODAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
Create documentation for Your MODAF project with ReporterPLUS. . . . . . . . . . . . . . . . . . . . 1368
Setting up ReporterPLUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368

Rational Rhapsody xxxvii

Table of Contents

Document structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369

Generating a MODAF document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
Troubleshooting ReporterPLUS and Rational Rhapsody for MODAF. . . . . . . . . . . . . . . . . . . . . . . . . . 1371
The Dependencies Linker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
Using the Dependencies Linker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
Troubleshoot the Dependencies Linker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373
General troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
Verify the Rational Rhapsody for MODAF Add On installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
Find icons missing from diagram tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
Check your Rational Rhapsody for MODAF model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374

The Rational Rhapsody automotive industry tools . . . . . . . . . . . . . . . . . . . . 1377

AUTOSAR modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
The AUTOSAR workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
Creating an AUTOSAR project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
Creating AUTOSAR diagrams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
Checking an AUTOSAR model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379
Import/export from/to AUTOSAR XML format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379
The AutomotiveC profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
Automotive-specific adaptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
Automotive-specific stereotypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
Simulink and StatemateBlock integration capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383
Fixed-point variable support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383
AutomotiveC properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383

StatemateBlock in Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385

Preparing a Rational StatemateBlock for Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . 1385
Creating the Rational StatemateBlock in Rational Rhapsody. . . . . . . . . . . . . . . . . . . . . . . . . . 1386
Connecting and synchronizing Rational Statemate and Rational Rhapsody . . . . . . . . . . . . . 1388
Troubleshooting Rational Statemate with Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . 1389

IBM Rational DOORS interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391

Installation requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
Rational DOORS version 7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
Solaris-specific information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
Using Rational Rhapsody with Rational DOORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393
Configuring Rational Rhapsody and Rational DOORS with the Gateway wizard . . . . . . . . . . . . . . . . . 1394
Requirements synchronization in Rational DOORS and Rational Rhapsody . . . . . . . . . . . . . . . . . . . . 1395
Navigating from Rational DOORS to Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396

xxxviii User Guide

 Table of Contents

Rational DOORS projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396

Invoking the Rational DOORS interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
Set export options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
Identify which formal modules to create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
Selecting Rational DOORS export options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
Linking the Rational DOORS data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400
Information stored in Rational DOORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1402
Rational DOORS information stored in Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
Data checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
Problem Description window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
Mapping Requirements to imported elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1406
Ending a Rational DOORS session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
Rational DOORS with Rational Rhapsody summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407

Rational Rose models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409

Importing a Rational Rose model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410
Setting up the XML map file for importing Rational Rose properties. . . . . . . . . . . . . . . . . . . . . . . . . . . 1413
Incremental import of Rational Rose models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1414
Before the import process starts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
About processing time and project size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416
Code import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417
Merging imported code to the imported Rational Rose model . . . . . . . . . . . . . . . . . . . . . . . . . 1418
How Rational Rose constructs and options map into a Rational Rhapsody model . . . . . . . . 1419
Imported association classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424

XMI exchange tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425

Using XMI in Rational Rhapsody development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
Exporting a model to XMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426
Examining the exported file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428
Importing an XMI file to Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430

Integrating Simulink components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431

Importing Simulink components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
Integration of the Simulink-generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433
Troubleshooting Simulink integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1434

Rational Rhapsody xxxix

Table of Contents

Creating Simulink S-functions

with Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435
Using Rational Rhapsody in conjunction with Simulink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435
Creating a Simulink S-function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435
S-function creation: behind the scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
Timing and S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1437

The Rational Rhapsody

command-line interface (CLI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1439
RhapsodyCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1439
Interactive mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
Socket mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
Command-line syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441
Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441
Order of commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
Include commands in a script file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
Exit after use of command-line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443
Command-line switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
Command-line commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446

Rational Rhapsody shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453

Accelerator keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453
Mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
Keyboard modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
Standard Windows keyboard interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455
Rational Rhapsody accelerator keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455
Application accelerators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455
Accelerators and modifier usage in diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1457
Code editor accelerators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458
Useful Rational Rhapsody Windows shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
Changing settings to show the mnemonic underlining. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460

Technical support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461

xl User Guide
 Table of Contents

Contacting IBM Rational Software Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461
Contacting Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462
About Rational Rhapsody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464
License Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464
Reporting Rational Rhapsody Problems from the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . 1465

Rational Rhapsody glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1467

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1531

Rational Rhapsody xli

Table of Contents

xlii User Guide

 Introduction to Rational Rhapsody

Welcome to IBM® Rational® Rhapsody®!

Systems engineers and software developers use Rational Rhapsody to create either embedded or
real-time systems. However, Rational Rhapsody goes beyond defining requirements and designing
a software solution. Rational Rhapsody actually implements the solution from design diagrams
and automatically generating ANSI-compliant code that is optimized for the most widely used
target environments.

With Rational Rhapsody, you have the ability to analyze the intended behavior of the application
much earlier in the development cycle by generating code from UML and SysML diagrams and
testing the application as you create it. Rational Rhapsody can be used for any of the following
items:

Reactivity for statecharts and events

Time-based behavior for timeouts
Multi-threaded architectures for active classes and protected classes
Real-time environments for direct support for several real-time, operating systems (RTOS)
Rational Rhapsody is semantically complete. Most items that you draw in Rational Rhapsody
UML diagrams, such as objects or events, have precise meaning in the underlying model. Objects
are the structural building blocks of a system.

Rational Rhapsody 1
Introduction to Rational Rhapsody

Rational Rhapsody translates these diagrams into source code in one of four high-level languages:
C++, C, Ada, or Java. Rational Rhapsody then allows you to edit the generated code and
dynamically roundtrip the changes back into the model and its graphical views. Rational Rhapsody
supplies four editions to create specific types of projects depending on your job requirements.

Rational Rhapsody Developer edition (C, C++, Java, and Ada are available, and this
edition required for Eclipse users.)
Rational Rhapsody Architect for Software edition (described in Creating projects in
Rational Rhapsody Architect for Software)
Rational Rhapsody Architect for Systems Engineers edition (described in Creating projects
in Rational Rhapsody Architect for Systems Engineers)
Rational Rhapsody Designer for Systems Engineers edition (described in Creating projects
in Rational Rhapsody Designer for Systems Engineers)
Only one Rational Rhapsody edition can be selected during installation.

Rational Rhapsody features

Rational Rhapsody includes the following features:

UML®, SysML™, and Functional C design modeling environment with Domain-Specific

Language (DSL) support including DoDAF*, MODAF*, and AUTOSAR*.
Predefined profiles supplying a coherent set of tags, stereotypes, and constraints for a
specific type of project. For more information, see Profiles.
MathWorks Simulink® Interface, SDL Interface, and Statemate® Interface available with
the Interfaces Add On can be used to validate your complete architecture while using the
best-in-class tools for control engineering, protocol development, and functional system
design.
Model verification with full model simulation and execution.
Static checking to ensure that the design is consistent.
Full application generation of C, C++, Java, and Ada in an integrated design environment.
Easily customizable real-time framework that separates high-level application design from
platform-specific implementation details with numerous adapters available such as
VxWorks, Windows CE, and Integrity. A full list is available in the Rational Rhapsody
release notes, and in addition you can create your own adapter.
Requirements modeling and traceability features with integration to leading requirements
management tools such as DOORS®* or text-based tools such as Microsoft® Word.
Easily integrate and create models from your existing C, C++, Java, and Ada code into the
modeling environment using reverse engineering and code visualization.

2 User Guide
 UML design essentials

Integration with leading IDEs such as Eclipse, Wind River® Workbench, and Green Hills®
Multi®.
Dynamic model-code associativity enabling design to be done using either code or
diagrams providing maximum flexibility while ensuring the two remain synchronized.
Improved test productivity and early detection of defects using Rational Rhapsody
TestConductor™ to automate tedious testing tasks, define tests with code and graphically
with sequence diagrams, statecharts, activity diagrams and flowcharts; and execute the
tests interactively or in batch mode.
XMI* (XML Metadata Interchange) and IBM® Rational Rose®* importing for integration
of legacy systems and reuse of existing code.
Full Configuration Management Interface* support with advanced graphical difference
and merging capabilities for use with tools such as IBM® Rational® Synergy™ or IBM®
Rational® ClearCase®.
Support for software product lines using class and object variants for components
Customization to meet your specific development needs using the Java API.
Generation of documentation using a range of tools, from a simple RTF report generator to
the full customization with Rational® Rhapsody® ReporterPLUS™.
* Capabilities are provided by optional add-ons.

UML design essentials

The Developer edition for C++, C, Java, and Ada and The Rational Rhapsody specialized editions
support UML to design your models.

The Unified Modeling Language (UML) is a third-generation modeling language for describing
complex systems. The Object Management Group® (OMG®) adopted the UML as the industry
standard for describing object-oriented systems in the fall of 1997. For more information on the
OMG, see their Web site at http://www.omg.org.

UML defines a set of diagrams by which you can specify the objects, messages, relationships, and
constraints in your system. Each diagram emphasizes a different aspect or view of the system
elements. For example, a UML sequence diagram focuses on the message flow between objects
during a particular scenario, whereas an object model diagram defines classes, their operations,
relations, and other elements.

Rational Rhapsody 3
Introduction to Rational Rhapsody

UML diagrams
The UML specification includes the following diagrams:

Use case diagram shows typical interactions between the system being designed and
external users or actors. Rational Rhapsody can generate code for actors in use case
diagrams to be used for testing a model.
Object model diagram shows the static structure of a system: the objects in the system
and their associations and operations, and the relationships between classes and any
constraints on those relationships.
Sequence diagram shows the message flow of objects over time for a particular scenario.
Collaboration diagram provides the same information as a sequence diagram but
emphasizes structure, whereas a sequence diagram emphasizes time.
Statechart defines all the states that an object can occupy and the messages or events that
cause the transition of the object from one state to another.
Activity diagram specifies a workflow or process for classes, use cases, and operations.
Activity diagrams provide similar information to statecharts, but are better for linear
step-by-step processes, whereas statecharts are better suited for non-linear or event-driven
processes.
Component diagram describes the organization of the software units and the
dependencies among these units.
Deployment diagram depicts the nodes in the final system architecture and the
connections between them. Nodes include processors that execute software components,
and the devices that those components control.
Structure diagram models the structure of a composite class; any class or object that has
an OMD can have a structure diagram. Object model diagrams focus more on the
specification of classes, whereas structure diagrams focus on the objects used in the
model.
In addition, a Flow Chart is available in the Rational Rhapsody product. You can use a flow chart
to describe a function or class operation and for code generation.

4 User Guide
 UML design essentials

UML views
You can use Rational Rhapsody to draw UML diagrams that provide different views of your
system. By editing the UML diagrams in Rational Rhapsody to create increasingly complex views,
you can add layers of perspective, detail, and specificity to your model until you have a complete
solution.

Structural views
Structural views show model elements and their relationships to each other. Model elements
include classes, use cases, components, and actors; their relationships include dependencies,
inheritances, associations, aggregation, and composition.

The following UML diagrams provide structural views:

Use case diagram

Object model diagram
Structure diagrams
Component diagram
Deployment diagram

Dynamic behavior views

Dynamic behavior views describe the system behavior. This includes state behavior, such as the
different states a class occupies, state transitions, forks and joins, and actions within a state; and
interactions, such as the collaborations occurring between classes during a particular scenario.

The following UML diagrams provide dynamic behavior views of the model:

Statechart
Activity diagram
Sequence diagram
Collaboration diagram

Model management views

Model management views show the hierarchical organization of the model. Object model diagrams
provide a model management view.

Rational Rhapsody 5
Introduction to Rational Rhapsody

Diagrams in Rational Rhapsody

Rational Rhapsody includes a graphic editor for each of the UML diagrams, enabling you to create
detailed views of your model. The graphic editors not only capture the design of your system, but
also generate implementation code.

Note
Rational Rhapsody diagrams have varying levels of code generation ability. Model elements
and implementation code can also be created from the browser.
Because Rational Rhapsody maintains a tight model-code associativity, you can easily generate
updated code when you make changes to the model. You can also edit code directly and bring
those changes into the model via the roundtrip feature. For more information about model-code
associativity, see Basic code generation concepts.

Partially constructive diagrams

Partially constructive diagrams generate code for some, but not all of the elements in the diagram.
Partially constructive diagrams include the following diagrams:

Use case diagrams

Sequence diagrams
Collaboration diagrams

Fully constructive diagrams

Fully constructive diagrams generate code for every element in the diagram. Fully constructive
diagrams include the following diagrams:

Object model diagrams

Component diagrams
Statecharts
Activity diagrams

6 User Guide
 Development methodology

Specify a model with Rational Rhapsody

To create a working model, you must create at a minimum an object model diagram. An object
model diagram generates the code necessary for a minimally functioning model.

A properly designed implementation, however, includes at a minimum object model diagrams,

statecharts or activity diagrams, and component diagrams. Object model diagrams and statecharts
can be considered to be design diagrams, because they are most often used in the design phase of a
project. Other diagrams are more helpful in other phases. For example, use case and sequence
diagrams are useful in the requirements analysis phase, where use case diagrams document
structural requirements and sequence diagrams document behavioral requirements.

Development methodology
A development methodology is a combination of a process, a tool, and a modeling language.
Rational Rhapsody is a UML-compliant modeling tool that is process-neutral and supports the
most common phases of any good development methodology. However, Rational Rhapsody is
particularly well-suited to an iterative process in which you build a number of model prototypes,
test, debug, reanalyze, and then rebuild the model any number of times, all within a single
development environment.

The ROPES™ process is an example of an iterative process that illustrates the use of Rational
Rhapsody and the UML across all typical process phases and activities. The following sections
provide a general overview of the phases involved in the ROPES process (including the subtasks
involved in general analysis, design, implementation, and test phases) and the Rational Rhapsody
tools appropriate for each phase. The Web site for IBM Rational modeling products contains
detailed information on ROPES.

Analysis
In the analysis phase, you define a problem, its possible solutions, and their characteristics.

Requirements analysis
Begin with the requirements analysis to identify the system requirements. What are the primary
system functions or system usages? Use case diagrams can capture these along with the external
actors that interact with the system.

Describe the expected behavior of the system as a whole by creating a series of “black-box”
sequence diagrams. In these, you will define the sequence of messages between external actors and
the system as a whole. You can create a number of sequence diagrams for each use case, where
each sequence diagram represents one scenario that could occur while carrying out that use case.
You can also use collaboration diagrams to specify the expected behavior of the system.

Rational Rhapsody 7
Introduction to Rational Rhapsody

Use the black-box sequence diagrams as the basis for creating statecharts, which realize all
possible scenarios. Statecharts specify the behavior of each object, or object implementation, as
opposed to sequence diagrams, which concentrate on requirements-based scenarios. Sequence
diagrams also serve as the primary test data in the testing phase; in later stages, use them to test
whether your system as a whole responds properly to the external messages that come into it. You
can also use activity diagrams to realize all possible scenarios. To review and analyze the
requirements in your project, you can use the advanced search facility and the table and matrix
tools.

Object analysis
While you are capturing system requirements, you should also define the entities and structural
relationships that will exist in the application you are creating and its domain or environment. This
should result in a structural (static) model of the system (a logical object model of the system).

Determine the subsystems of your system. What are their responsibilities and relationships? These
subsystems become the basis of the packages, or collections of classes, within your system.

Determine the key objects or classes in these subsystems and define their responsibilities,
descriptions, and their relations to other classes. Use object model diagrams to create these classes
and their relations. Using sequence diagrams and statecharts, define the behavior and interactions
of these essential objects.

You can also use the code generation and animation tools to execute and debug these higher-level
analysis models.

Design
In the analysis phase, you came up with several possible solutions to your problem. In the design
phase, you choose one of those solutions and define how it will be implemented. As with the
analysis phase, the design phase has more than one component. Just as the analysis phase should
conclude with some result, a full set of use cases and a logical object model of the system, the
design phase should also provide results: task and deployment models, and more refined logical
object models.

Architectural design
Define the major architectural pieces of the system. What are the high-level parts? Define what the
system domains are and which key classes fit in each domain. Which are your composite classes?
In this analysis, you should also map classes, packages, and components to the relevant physical
parts of your system (the processors and devices). Define which libraries and executables are
necessary in your model. You are creating the task and deployment models for your system. To
help with this, you can apply UML design patterns as appropriate for your system.

8 User Guide
 Development methodology

Mechanistic design
Continue to detail the internal workings of your system, breaking it down into smaller pieces and
more classes, if necessary. Use “white-box” sequence diagrams to depict the class interactions
within the system. Define the collaborations that are required to realize certain core cases by
creating collaboration diagrams. Add to your model the “glue” objects that are used in the UML
design patterns that you use. Again, you can use the code generation and animation tools to debug
and test the model at this point. Your end result should be a more refined set of logical object
models.

Detailed design
Continue to fill in the details of your design. Get your individual classes working; fully define their
constraints, internal data structures, and message passing behavior. Use activity diagrams and
statecharts to define correct behavior. At this stage, you will probably begin typing in extra code in
the implementation boxes in various diagrams. Use component diagrams to define the physical
artifacts of your system and to include the libraries, executables, or legacy code you have deemed
necessary for your model. Make low-level decisions about implementations, such as choosing
static or dynamic instantiations. This should result in a more refined logical object model (or
models) of your system.

Implementation
The implementation phase is essentially the code generation and unit testing phase. Using Rational
Rhapsody, write the code that is not generated automatically, such as the bodies of non-statechart
operations. These include constructors, destructors, object methods, and global functions. Use the
animation and tracing tools to test and debug sections of code and to make decisions about any
optimization
trade-offs.

The testing phase

In the testing phase, you determine not only whether your model is working, but whether it meets
the requirements that you set in the analysis phase. Your end result should be a working system.

Rational Rhapsody includes the following features to assist with the testing phase:

Animator creates test scripts to apply external test stimuli to the system.
Tracer performs white, gray, and black-box regression testing. It also provides
performance testing based on timing annotations or on a simulated time facility.
Sequence diagram comparison Automatically compares requirement sequences with
implementation sequences.

Rational Rhapsody 9
Introduction to Rational Rhapsody

Rational Rhapsody tools

Rational Rhapsody consists of the following set of tools that interact with each other to give you a
complete software design environment:

The Rational Rhapsody browser

The Favorites browser

Graphic editors

Code generator

Animator

Utilities, including reverse engineering, Web-enabling devices, XMI generation, COM and
CORBA® support, and Visual Basic® for Applications
Third-party interfaces such as Eclipse, Rational Rose import, and CM tools

The Rational Rhapsody browser

The Rational Rhapsody browser shows a comprehensive display of the system with a clear
overview of your entire model. Views filter the display to optimize usability for a particular task.
During an animation session, the browser dynamically displays object instances as the model
executes.

For more details about the uses of the browser, see Browser and Browser filter; and for details on
the model display features for the browser, see Browser techniques for project management.

10 User Guide
 Rational Rhapsody tools

The Favorites browser

You can use the Favorites browser to create a favorites list, which is a list of items (model
elements) that you are most interested in for the opened Rational Rhapsody model. This is
analogous to the favorites functionality for a Web browser. You might find the Favorites browser
most useful with Rational Rhapsody models that are very large, which can make it difficult to find
commonly used model elements in the Rational Rhapsody browser. The Favorites browser should
help you manage large and complex projects by making it easier to focus on and easily access
model elements of particular interest to you.

The following figure shows a sample Favorites browser:

Your favorites list is saved in the <projectname>.rpw file, as well as the position and visibility of
the Favorites browser, so that when you open the project the next time, your settings are
automatically in place. Note that when multiple projects are loaded, the Favorites browser shows
the favorites list for the active project, as described in Setting the active project.

For more information about the Favorites browser, see The Favorites browser.

Rational Rhapsody 11
Introduction to Rational Rhapsody

Diagram tools
When you have a diagram open on the drawing area in Rational Rhapsody, a panel of diagram
drawing tools for the currently displayed diagram type also appears. You can move this panel to
different locations and close it.

Different tools are available depending on the type of diagram displayed in the drawing area.

This accordion menu also contains a Common section for tools for common additions to diagrams
and a Free Shapes section for tools that let you draw elements freehand in a diagram.

12 User Guide
 Rational Rhapsody tools

Graphic editors
You can use the graphic editors to analyze, design, and construct the system using UML diagrams.
Diagrams enable you to observe the model from several different perspectives, like turning a cube
in your hand to view its different sides. Depending on its focus, a diagram might show only a
subset of the total number of classes, objects, relationships, or behaviors in the model. Together,
the diagrams represent a complete design.

Rational Rhapsody adds the objects created in diagrams to the Rational Rhapsody project, if they
do not already exist. Conversely, Rational Rhapsody removes elements from the project when they
are deleted from a diagram. However, you can also add existing elements to diagrams that do not
need to be added to the project, and remove elements from a diagram without deleting them from
the model repository.

Use case diagram editor provides tools for creating use case diagrams, which show the
use cases of the system and the actors that interact with them. See Use case diagrams.
Object model diagram editor provides tools for creating object model diagrams, which
are logical views showing the static structure of the classes and objects in an object-
oriented software system and the relationships between them. See Object model diagrams.
Sequence diagram editor provides tools for creating sequence diagrams, which show
interactions between objects in the form of messages passed between the objects over
time. If you run animated code with the Animator, you can watch messages being passed
between objects as the model runs. See Sequence diagrams.
Collaboration diagram editor provides tools for creating collaboration diagrams, which
describe how different kinds of objects and associations are used to accomplish a
particular task. Collaboration diagrams and sequence diagrams are both interaction
diagrams that show sequences. Sequence diagrams have a time component, whereas
collaboration diagrams do not.

Like sequence diagrams, collaboration diagrams show the message flow between
different classes. However, collaboration diagrams emphasize object relationships
whereas sequence diagrams emphasize the order of the message flow. For a particular task
or interaction, a collaboration diagram can also show the individual objects that are
created, destroyed, or exist continuously for the duration of the task. See Collaboration
diagrams.
Statechart editor provides tools for creating statecharts, which define the behaviors of
individual classes in the system.

Statecharts show the states of a class in a given context, events that can cause transitions
from one state to another, and actions that result from state transitions. Rhapsody
generates function bodies from information entered into statecharts. If you run animated
code with the animator, you can watch an object change states as it reacts to various
messages, events, and triggered operations that you generate. See Statecharts

Rational Rhapsody 13
Introduction to Rational Rhapsody

Activity diagram editor provides tools for creating activity diagrams. Activity diagrams
show the lifetime behavior of an object, or the procedure that is executed by an operation
in terms of a process flow, rather than as a set of reactions to incoming events. When a
system is not event-driven, use activity diagrams rather than statecharts to specify
behavior. See Activity diagrams.
Component diagram editor provides tools for creating component diagrams, which
show the dependencies among software components, such as library or executable
components. Component diagrams can also show component dependencies, such as the
files (or other units) that are contained by a component, or the connections or interfaces
among components. See Component diagrams.
Deployment diagram editor provides tools for creating deployment diagrams, which
show the run-time physical architecture of the system. The physical architecture of a
running system consists of the configuration of run-time processing elements and the
software components, processes, and objects that live on them. A deployment diagram
graphs the nodes in the system, representing various processors, connected by
communication associations. See Deployment diagrams.
Structure diagram editor provides tools for creating structure diagrams, which model the
structure of a composite classes. See Structure diagrams.

Note
All the diagrams use UML notation.
The FunctionalC profile has these diagrams available to construct a C model:

Use case diagram

Statechart
Build diagram
Call Graph diagram
Flow Chart
Message diagram
File diagram

14 User Guide
 Rational Rhapsody tools

Code generator
The code generator synthesizes complete production-quality code from the model to free you from
low-level coding activities. Rational Rhapsody generates code primarily from OMDs and
statecharts, but also from activity and other diagrams. Allowing the tool to generate code
automatically for you lets you concentrate on higher-level system analysis and design tasks. For
more information, see Basic code generation concepts.

Animator
The animation facility lets you debug and verify your software at the design level rather than the
compiler level. For more information, see Animation.

Utilities
In addition to the core UML-based design features, Rational Rhapsody provides a number of
utilities to assist with development including the following utilities:

Dynamic reverse engineering (see Reverse engineering)

Roundtrip (see Basic code generation concepts)
Check model (see Checks)
Web-enabling of Rational Rhapsody models (see Managing Web-enabled devices)
Standard and customizable report generation with Rational Rhapsody Reporter and
ReporterPLUS (see Reports)
Import of model elements from libraries and external source files including XMI exchange
tools, StatemateBlock in Rational Rhapsody, and Importing DoDAF diagrams from Rational
System Architect.
Add to Model and multiuser collaboration
Component download
File comparison and merging, as described in Parallel project development and DiffMerge
Web Collaboration, as described in Viewing and Controlling of a Model via the Internet

Rational Rhapsody 15
Introduction to Rational Rhapsody

Third-party interfaces
The following third-party software interfaces can be accessed through the Rational Rhapsody
interface:

Configuration management tools including support for the Microsoft Source Code Control
(SCC) standard
Visual Studio standard or professional edition (see Visual Studio IDE with Rational
Rhapsody)
Integrated VBA Interface for development and macros
IDE interface to the Tornado™ development environment (see Co-debugging with
Tornado)

Code editors (such as CodeWright™)

Source debuggers (in addition to IDEs)
Eclipse (for information about the Eclipse implementations, see Eclipse platform
integration and Using the Rational Rhapsody Workflow Integration with Eclipse)

16 User Guide
 Rational Rhapsody windows

Rational Rhapsody windows

When creating or editing a project, the Rational Rhapsody workspace has the following windows:

Menu bar lists the primary functions as File, Edit, View, Code, Tools, Layout, Windows,
and Help. Many of the Rational Rhapsody functions available on the menus are also
accessible from Rational Rhapsody shortcuts and buttons across the top of the Rational
Rhapsody interface, as described in Rational Rhapsody project tools.
Browser displays the contents of the project and has several views to choose from. See
Browser.
Diagram drawing area contains the diagram editor windows, which can be moved and
resized. See Diagram drawing area.
Diagram Tools contains the drawing tools for each diagram type and opens in a panel next
to the diagram open in the drawing area in Rational Rhapsody. See Diagram tools.
Different buttons are displayed in the panel depending on the type of diagram displayed in
the drawing area. See the descriptions of the diagrams for explanations of each diagram
drawing tool. This accordion menu also contains a Common section for tools for
common additions to diagrams and a Free Shapes section for tools that let you draw
elements freehand in a diagram.
Diagram Navigator provides a bird’s eye view of the diagram that is currently displayed.
See Diagram navigator.
Output window has several tabs, each displaying different types of Rational Rhapsody
output including search results. See Output window.
In addition, you can open two windows from the View menu:

Features window displays details of selected model element. By default, it displays as a

floating window, but you can dock it to the main window in any position. See The
Features window.
Active code view generates and displays code for the selected model element. See Active
Code View window.
When you open Rational Rhapsody for the first time, the Welcome window displays.

Rational Rhapsody 17
Introduction to Rational Rhapsody

The following figure shows the default arrangement of the Rational Rhapsody windows.

Note the following information:

You can reposition each window within the Rational Rhapsody workspace to suit your
preferred work style.
To dock or undock a window quickly, double-click the title bar.
To reposition a window, click the title bar and drag-and-drop the window to the intended
location.

18 User Guide
 Rational Rhapsody windows

View menu commands

The Rational Rhapsody View menu allows you to customize the display of the Rational Rhapsody
interface areas.

View > Status Bar

The status bar at bottom of the main window displays the current mode (for example, GE MODE)
and the date and time. Use this menu command to toggle the status display on and off.

View > Favorites

Use this menu command to display The Favorites browser for your project.

View > Features

Use this menu command to display The Features window for a selected project element.

View > Description

Use this menu command to display and edit the description of a selected element as it is on the
Description tab of the Features window.

View > Tags

Use this menu command to display and edit the tags of a selected element as it is on the Tags tab of
the Features window.

View > Relations

Use this menu command to display and edit the relations of a selected element as it is on the
Relations tab of the Features window.

View > Properties

Use this menu command to display the properties associated with a selected project element. For
more information, see Properties tab.

View > Browser

The browser displays a tree structure of your project. You can also use this area to edit and
restructure your model. For more information, see Creating hyperlinks on the Rational Rhapsody
browser.

View > Label Mode

If you want to work exclusively with the label names of the elements, choose the Label Mode
command on the View menu. For more information about this work mode, see Label mode.

Rational Rhapsody 19
Introduction to Rational Rhapsody

View > Workbar Mode

The tabs above the diagram drawing area are displayed when the Workbar Mode is selected. To
switch off the tabs in the drawing area, clear the check mark next to Workbar Mode on the View
menu.

View > Gradient Mode

The Gradient Mode displays the project diagrams with a shaded background.

View > Full Screen Mode

The Full Screen Mode displays Rational Rhapsody as the only application on your computer
screen. To redisplay the other programs you have running and end this mode, press the Esc key.

View > Maintain Window Content

The part of the diagram displayed in the drawing area is called the viewport. To specify whether to
display the viewport regardless of any sizing or reposition of the diagram drawing window, choose
the Maintain Window Content on the View menu. For more information, see Maintaining the
window content.

View > Output Window

Use this menu command to open the Output window manually. The Output Window opens
automatically when a process produces output for display. For more information, see Output
window.

View > Active Code View

To display code for an element selected in the browser, choose View Active Code View. For more
information, see Active Code View window.

View > Bird’s Eye

Use this menu command to show or hide the Bird’s Eye window, a view of the entire diagram with
a rectangular focus area showing the portion of the diagram is currently displayed in the drawing
area. For more information about this feature, see The Bird’s Eye (diagram navigator)

View > Pop Context

To return to the origin point of a hyperlink, choose this View menu command or press
Ctrl+P.

View > Toolbars > Diagrams

Use this menu command to show or hide the diagram control toolbar.

20 User Guide
 Rational Rhapsody windows

View > Toolbars > Code

Use this menu command to show or hide the code access toolbar.

View > Toolbars > Browser Filter

Use this menu command focus the browser display on the portion of the project related to your
current task.

View > Toolbars > Start Target Monitoring

Target monitoring is background animation of a C application from a target with unknown or
limited resources or limited monitoring for application execution on the target. This menu
command displays the tools used to set up and start monitoring a C application created using the
MicroC profile.

View > Toolbars > Target Monitoring

Use this toolbar to watch the C application execution on the target. However, this feature cannot be
used to control application execution.

View > Toolbars > VBA

Use this menu command to display the Rational Rhapsody Visual Basic for Applications (VBA)
Interface editor and macro creation facility.

Rational Rhapsody 21
Introduction to Rational Rhapsody

Browser
The browser displays a hierarchy of your project and provides easy access to the elements and
diagrams it contains. You can filter the display with several view options. Browser techniques for
project management provides detailed descriptions of browser elements and views.

By default, the browser is docked at the upper, left corner of the Rational Rhapsody main window.

To open the browser, choose View > Browser.

Choose Tools > Browser open multiple instances of the browser to simplify the process of
navigating between elements. This feature is particularly useful during animation.
In addition, you can select multiple elements in the browser and perform any of these operations
on all of them:

Move them to another browser element by dragging and dropping them over the target
element
Copy them to another browser element by dragging and dropping them over the target
element
Delete all of them at the same time

22 User Guide
 Rational Rhapsody windows

Diagram drawing area

The drawing area displays the graphic editors and code editors. Editors can be moved and resized
within the drawing area. When you open more than one editor, tabs are displayed at the bottom of
the drawing area so you can easily move between the open diagrams or generated code files. In
addition, you can tile or cascade the windows that contain the different diagrams.

Each diagram includes a title bar, which contains the name of the diagram and its type. A modified
diagram has an asterisk (*) added to the end of its name in the title bar.

For a description of the graphic editor windows, see Graphic editors. For a description of the
default code editor, see The Internal code editor.

Maintaining the window content

When you resize the drawing area (for example, to increase the available drawing space), some of
the diagram might move out of the visible area of the window. The part of the diagram displayed in
the window is called the viewport. You can specify whether to display the viewport regardless of
window manipulation using two different methods:

Choose View > Maintain Window Content.

Set the General::Graphics::MaintainWindowContent property to Checked.
Using this functionality, the elements are scaled according to the zoom factor so you see the same
elements in the window regardless of scaling.

Changing the drawing area window display

Rational Rhapsody uses these standard Microsoft Windows features to change the shape and
display design of the diagram drawing area:

Manual resizing by dragging the edge of the window

Maximize/Minimize and Restore buttons
Window > Tile
Window > Cascade

Rational Rhapsody 23
Introduction to Rational Rhapsody

Diagram navigator
The Diagram Navigator provides a bird's eye view of the diagram that is currently being viewed.
This can be very useful when dealing with very large diagrams, allowing you to view specific
areas of the diagram in the drawing area, while, at the same time, maintaining a view of the
diagram in its entirety.

The Diagram Navigator contains a depiction of the entire diagram being viewed, and a rectangle
viewport that indicates which portion of the diagram is currently visible in the drawing area.

For detailed information about using the Diagram Navigator window, see The Bird’s Eye (diagram
navigator).

Output window
The Output window is where Rational Rhapsody displays various output messages. You can use
the tabs on the Output window to navigate easily among the different types of output messages:

The Log tab shows all the messages from all the other tabs of the Output window (except
for Search Results) in text (meaning non-tabular) format.
The Build tab shows the messages related to building an application in tabular format.
The Check Model tab shows the messages related to checking the code for a model in
tabular format.
The Configuration Management tab shows the messages related to configuration
management actions for a model in text format.
The Animation tab shows the message related to animating a model in text format.
The Search Results tab shows the results from searches of your model in tabular format.
Note that this tab might not appear until you perform a search.
By default, the Output window is located at the bottom portion of the main Rational Rhapsody
window. Also by default, when you generate, build, or run an application; do a search, a CM
action, or a check model, Rational Rhapsody opens the Output window.

24 User Guide
 Rational Rhapsody windows

Log tab
The Log tab serves as a console log. It shows all the messages from all the other tabs of the Output
window (except for Search Results) in text (meaning non-tabular) format. The messages that
appear on the Check Model, Build, Configuration Management, and Animation tabs appear on
the Log tab too, but always in text format. For the check model and build functions, you can view
their messages on the Check Model and Build tabs in tabular format or on the Log tab in text
format, depending on your preference. The Log tab displays messages in text format after a build
function is performed.

Note that you can right-click on the Log tab to use the Clear, Copy, Paste, and Hide commands.

The following figure shows the Build tab for the same build function. As you can see, the
messages provide the same type of information, though the presentation is in a tabular format.

On the Log, Check Model, and Build tabs, you can double-click an item on the tab and, if
possible, Rational Rhapsody opens either the relevant model element (for example, the Features
window for an association that might be causing an error) or to the code source. From whichever
opens, you can make corrections or view the item more closely.

Rational Rhapsody 25
Introduction to Rational Rhapsody

Check Model tab

Rational Rhapsody analyzes and organizes the results of checking the code for a model and
displays the results on the Check Model tab. Check messages are grouped by a severity hierarchy,
and provide you with the location, domain, and integrity for an item, where possible.

Before generating code, Rational Rhapsody automatically performs certain checks for the
correctness and completeness of the model. In addition, you can perform selected checks at any
time during the design process. To check the code for a model, choose Tools > Check Model and
then the name of the configuration for the model. For more information about checking the code
for a model, see Checks.

26 User Guide
 Rational Rhapsody windows

The following table explains what type of information available on the Check Model tab.

Column Explanation
Checks Shows the check results tree grouped by three levels and in the hierarchy
shown as follows:
Level 1, Severity: Where the elements listed are grouped under the three
optional severity levels as follows:

Errors

Warnings

Info
The grouping is determined by the severity level of each added check. If there
is a + icon next to a label, click it to expand or collapse the list. In addition, to
the right of each severity level name is the number of problems in the security
level.
Level 2, Checks: Where each check that produces errors/problems when it is
executed is shown in the list indented under its relevant severity level (for
example, Default Names under Warnings). A check is considered a group that
holds under it all its related problems. Each check in the list shows also its
domain and integrity properties. In addition, to the right of each check name is
the number of problems the check contains. There are 10 Default Name
warnings.
Level 3: Check Elements, where each problem found when performing a
specific check is shown as a list item under the relevant check name. Problems
are represented by model elements and shown with the relevant name, type
icon, and model location path (for example, ServicePerson:
itsServiceDishwasher, the first item in the Default Names check group in the
Warnings severity level).
Location Shows, for each problem found, the location of an element in the model.
Domain Shows, for each check in the list, its domain property. This includes domains
that are from user-defined checks.
Integrity Shows, for each check in the list, its integrity property value.

Rational Rhapsody 27
Introduction to Rational Rhapsody

You can double-click an item on the Check Model tab and if possible, Rational Rhapsody brings
you to the relevant model element (for example, the Features window for an association) or to the
code on which you can make corrections or view the item more closely. Note that if you click a
level heading, you expand or collapse the list for the level.

Note that you can right-click on the Check Model tab to use the Copy All and Clear All
commands.

28 User Guide
 Rational Rhapsody windows

Build tab
The Build tab shows the messages related to building an application.

This tabular view shows the following types of information:

Column Explanation
Severity Error messages. Errors appear when the model fails to build. You must fix
errors before the model can be built. Rational Rhapsody parses the information
provided by the compiler to develop the list of error messages. Note that there
can be two types of error (and warning) messages: model element and code
error. Model element-type errors (and warnings) are those that Rational
Rhapsody can correspond to specific model elements in a project. Code error-
type errors are those that Rational Rhapsody cannot find any corresponding
model element.
Warning messages. Warnings have no effect on whether the model is built, but
you should review them and address them if necessary as they might have an
effect on whether the model builds as expected. Rational Rhapsody parses the
information provided by the compiler to develop the list of warning messages.
Informational messages. These messages are messages that are not warnings
or errors and they have no effect on the building of the model.
Model Element Applicable to error and warning messages only, shows the Rational Rhapsody model
element and its applicable Rational Rhapsody icon. If no related model element is
found, the error is assumed to be a code error-type error.
File Applicable to error and warning messages only, shows the file name and line number
where an error/warning was found.
Description Descriptions are provided by the compiler.
More Details Applicable to error and warning messages only, and only if available, show more
details as provided by the compiler.

Rational Rhapsody 29
Introduction to Rational Rhapsody

By default, you see all the messages for a build. If this is not the case, you can select All Build
Messages View from the menu in the upper-left corner of the Output window for the Build tab.

You can use the menu in the upper-left corner of the Output window for the Build tab to choose
other views. The following figure shows the Build tab with Model Element Messages selected,
which shows only items with a severity of Error or Warning that also have references to a model
element. In addition, information messages, code error-type errors and warnings are filtered out.

The following figure shows the Build tab with All Errors and Warnings View selected, which
shows only error and warning messages (so that information messages are filtered out).

30 User Guide
 Rational Rhapsody windows

Note that you can double-click an item on the tab and, if possible, Rational Rhapsody opens either
the relevant model element (for example, the Features window for an association that might be
causing an error) or to the code source. From whichever opens, you can make corrections or view
the item more closely. In the following figure, double-clicking the “Code Error” item on the Build
tab in the lower portion of the figure, opens the code for that item in the upper-right portion of the
figure.

You can right-click the Build tab to use the Copy All and Clear All commands.

Note
By default, the Build tab displays after you run a build. If you want the Log tab to
automatically display instead after a build, you can set the
CG::General::ShowLogViewAfterBuild property to Checked.

Supported compilers
The compilers from Microsoft, Java, and Cygwin are fully supported, which means that Rational
Rhapsody is able to analyze the output from their compilers and show the correct severity levels
for their messages. For all other compilers, their output will only show Informational messages.

Rational Rhapsody 31
Introduction to Rational Rhapsody

Configuration Management tab

The Configuration Management tab shows messages related to configuration management
actions for a model. You can right-click on the Configuration Management tab to use the Clear,
Copy, Paste, and Hide commands.

Animation tab
The Animation tab shows messages related to animating a model. For more information about
animation, see Animation. You can right-click on the Animation tab to use the Clear, Copy,
Paste, and Hide commands.

Search Results tab

The Search Results tab shows results from searches of your model. Note that this tab might not
appear until you perform a search (for example, choose Edit > Search and select the New Tab
check box). For more information about doing searches, see Searching models.

32 User Guide
 Rational Rhapsody project tools

Active Code View window

The Active Code View window displays code for an element selected in the browser. Whenever
you make changes to the model, Rational Rhapsody regenerates the code and updates it in the
Active Code View window.

To open the Active Code View window, choose View > Active Code View.

Specification tab
The Active Code View window has two tabs, Specification and Implementation. The
Specification tab displays the specification code.

Implementation tab
The Active Code View window has two tabs, Specification and Implementation. The
Implementation tab displays the implementation code.

Welcome window
Rational Rhapsody typically starts up with the Welcome window open. The Welcome window
provides links to help you get started quickly. The Welcome Screen appears each time you open
Rational Rhapsody unless you clear the Show Welcome Screen at startup check box at the
bottom of the window. You can view the Welcome window at any time by choosing Help >
Welcome Screen.

Restoring the Welcome window

To restore the display-on-startup setting for the Welcome window, do either of the following
actions depending on your situation:

If Rational Rhapsody starts up without opening the Welcome window, choose Help >
Welcome Screen. Notice that doing this automatically selects the Show Welcome Screen
at startup check box at the bottom of the window.
If you have cleared the Show Welcome Screen at startup check box but have not yet shut
down Rational Rhapsody, return to the Welcome window (select the Welcome tab in the
drawing area or choose Help > Welcome Screen) and select the Show Welcome Screen
at startup check box.

Rational Rhapsody project tools

The Rational Rhapsody project tools allow you to perform model design and development tasks
using groups of toolbar buttons in the browser, drawing area, and output window. If a button is

Rational Rhapsody 33
Introduction to Rational Rhapsody

disabled or not displayed, the operation represented by the button is unavailable for the currently
displayed project items.

Browser filter
The browser filter lets you display only the elements relevant to your current task. Click the down
arrow at the top of the browser to display the menu of filter options.

The filter is set to Entire Model View (default). For detailed information about the other options,
see Rational Rhapsody browser menu options. You can also display the browser filter using View >
Toolbars > Browser Filter.

34 User Guide
 Rational Rhapsody project tools

Standard tools
The Standard toolbar provides quick access to the standard tools in Rational Rhapsody. To
display or hide this toolbar, choose View > Toolbars > Standard.

The Standard toolbar includes the following tools:

Tool
Name Description
Button
New Creates a project. This button executes the same command as File > New.

Open Opens an existing project. This button executes the same command as File > Open.

Save Saves the current project. This button executes the same command as File > Save.

Cut Cuts the selection to the clipboard. This button executes the same command as
Edit > Cut.

Copy Copies the selection to the clipboard. This button executes the same command as
Edit > Copy.

Paste Pastes the contents of the clipboard. This button executes the same command as
Edit > Paste.

Format Painter Used for copying formatting from one element to another element in the same
diagram.

Print Prints the active view. This button executes the same command as File > Print.

About Opens the About Rational Rhapsody window, which displays the product version
information. You can also choose Help > About Rhapsody to open the window. In
addition, when you have the About Rhapsody window open, you can click the
License button to open the License Details window.
Undo Undoes the last operation you performed in the model. This button executes the
same command as Edit > Undo.

Redo Reverses the undo command. This button executes the same command as Edit >
Redo.

Search Opens the Search window for a term in the model. This button executes the same
command as Edit > Search.

Rational Rhapsody 35
Introduction to Rational Rhapsody

Tool
Name Description
Button
References Opens a list of elements that reference the selected element.
This button executes the same command as right-clicking the selected element in
the browser and selecting References.
Locate in Locates the selected diagram element in the browser.
Browser This button executes the same command as the Locate button in the Features
window and Edit > Locate in Browser.
Delete Deletes the current selection from model. This button executes the same command
as Edit > Delete.

Edit menu commands

The Rational Rhapsody Edit menu lets you access and change text and diagrams using the
following menu commands. Many of these menu commands are also represented as toolbar
buttons, as described in Standard tools.

Edit > Undo

Rational Rhapsody allows you to undo the last 20 operations performed on the project.

Edit > Redo

You can redo the operation that was most recently undone using Edit > Undo or the Undo button.
Redo is not active until you have used Undo at least once.

Edit > Cut

This menu command removes the selection from the model and puts it into the Windows clipboard
for possible pasting in another location.

Edit > Copy

This menu command makes a copy of the selection and puts it into the Windows clipboard for
possible pasting in another location.

Edit > Paste

This menu command copies and previously cut or copied selection from the Windows clipboard
into a different location.

36 User Guide
 Rational Rhapsody project tools

Edit > Delete

The Delete menu command removes the selected item from the entire active project. In the
browser, it always deletes an object from the entire model including all diagrams. Before the delete
operation is completed, a confirmation message displays.

Edit > Search

Use this menu command to perform a quick search of the model or a more advanced search for text
or model elements. This facility displays the results in the Output window. See Searching models.

Edit > Advanced Search and Replace

Use this menu command to perform more complex searches, such as identifying only the units in
the model or locating unresolved elements. See Advanced search and replace features.

Edit > Search Inside Selected

Use this menu command to perform a search within the item you selected on the Rational
Rhapsody browser. See Searching models.

Tools for Generating and running code

The Code toolbar provides quick access to frequently used Code menu commands.

The Code toolbar includes the following tools:

Tool Button Name Description

Make Builds the active configuration. You must generate code
before you can build the configuration.
This button executes the same command as Code >
Generate > Build run XXX.exe.
Stop Make/ Stops the make process or the execution while it is in
Execution progress. This button executes the same command as Code
> Stop.

Run Executable Runs the executable image. This button executes the same
command as Code > Run XXX.exe.

Generate/ Generates code, builds the configuration, and runs the

Make/Run executable image. This button executes the same command
(GMR) as Code > Generate/Make/Run.

Disable/Enable Disables or enables dynamic model-code associativity. The

Dynamic Model button displays as two connected arrows when DMCA is
Code active, and two disconnected arrows when DMCA is inactive.
Associativity See Deleting Redundant Code Files.

Rational Rhapsody 37
Introduction to Rational Rhapsody

Tool Button Name Description

Current Contains a list of all components in the project. To change the
Component active component, select it from the drop-down list.

Current Contains a list of all configurations in the active component.

Configuration To change the active configuration, select it from the
drop-down list.

38 User Guide
 Rational Rhapsody project tools

Tools for managing and arranging windows

The Windows toolbar provides quick access to Rational Rhapsody windows, such as the browser
and the Features window. You can also access these commands from the View menu. To display or
hide this toolbar, choose View > Toolbars > Windows.

The Windows toolbar includes the following tools:

Tool
Name Description
Button
Browser Toggles between showing and hiding the browser.

Show/Hide Toggles between showing and hiding the Features window for the current element.
Features

Show/Hide Toggles between showing and hiding the Active Code View window.
Active Code
View
Show/Hide Toggles between showing and hiding the Output window.
Output Window

Toggle Arrange Toggles between two standard desktop arrangements.

Options Alternatively, choose Window > Arrange Options.
Use Windows > Arrange Icons to manipulate the arrangement of the desktop.
Bird’s Eye Toggles between showing and hiding the Bird’s Eye window. You can also press
Window Alt+F5 to perform the same operation. For more information about this feature, see
The Bird’s Eye (diagram navigator).

Back Displays the previously displayed window. This operation is also available using
Window > Back.

Forward Displays the window in the opposite direction from Back. This operation is also
available using Window > Forward.

Note
The Back and Forward navigation is unavailable on Linux. This is for Windows systems
only.

Rational Rhapsody 39
Introduction to Rational Rhapsody

Tools for the Favorites browser

The Favorites toolbar provides tools for the Favorites browser. To display or hide this toolbar,
choose View > Toolbars > Favorites.

For more information about the Favorites browser and about the Favorites toolbar, see The
Favorites browser.

Tools for the VBA interface options

The VBA toolbar provides quick access to Rational Rhapsody VBA Interface options. To display
or hide this toolbar, choose View > Toolbars > VBA.

The VBA toolbar includes the following tools:

Tool
Name Description
Button
VBA Editor Opens the VBA editor.

Show Opens the VBA properties window.

Properties

Macros Opens the Macros window so you can create VBA macros.

Design Mode Runs VBA in design mode.

Tools for animation

When you run an executable model with instrumentation set to Animation, Rational Rhapsody
displays the Animation toolbar. This toolbar automatically appears during an animation session.
To display or hide this toolbar during an animation session, choose View > Toolbars >
Animation.

For more information about animation and about this toolbar, see Animation.

Tools for creating and editing diagram elements

The Diagram Tools panel provides access to tools used in creating and editing diagrams in the
graphic editors. Each graphic editor has a unique set of diagram tools. To display or hide the
drawing tools for the current diagram, choose View > Toolbars > Drawing.

40 User Guide
 Rational Rhapsody project tools

For more information about modeling toolbars, see Graphic editors.

Tools for common annotations

Use the Common tools, which are displayed in its own section on the Diagram Tools panel, to
add annotations (constraints, comments, and requirements) to a diagram. To display or hide the
Diagram Tools panel, choose View > Toolbars > Drawing.

For information about annotations for diagrams, see Annotations for diagrams.

The Common toolbar includes the following tools:

Tool
Name Description
Button
Note Creates a documentation note. Click the button and use the mouse to draw the note
in the diagram.
This is the type of note available with previous versions of Rational Rhapsody. The
note displays in the diagram, but not in the browser.
Constraint Creates a constraint. This button executes the same command as Edit >
Add New > Constraint.

Comment Creates a comment. This button executes the same command as Edit > Add New >
Comment.

Requirement Creates a requirement. This button executes the same command as Edit >
Add New > Requirement.

Anchor Creates an anchor for a constraint, comment, or requirement.

Constraint/
Comment/
Requirement to
Item

Tools for zooming diagram views

The Zoom toolbar contains the zoom tools you can use with all the different diagram types. These
tools are also available in View > Zoom/Pan. To display or hide this toolbar, choose View >
Toolbars > Zoom.

For more information about zoom function and the Zoom toolbar, see Zoom.

Rational Rhapsody 41
Introduction to Rational Rhapsody

Tools for formatting text

The Format toolbar provides tools that affect the display of text in your diagrams, such as font,
size, color, and so on. In addition, you can access these options by selecting Edit > Format >
Change. To display or hide this toolbar, choose View > Toolbars > Format.

For more information about the Format toolbar, see Format text on diagrams.

Tools for the layout of elements

The Layout toolbar provides quick access to tools that help you with the layout of elements in
your diagram, including a grid, page breaks, rulers, and so on. To display or hide this toolbar,
choose View > Toolbars > Layout.

For more information about the Layout toolbar, see Layout toolbar.

Tools for free shapes

Use the Free Shapes tool, which are displayed in its own section on the Diagram Tools panel, to
draw elements freehand in a diagram. To display or hide the Diagram Tools panel, choose View >
Toolbars > Drawing.

For more information about the graphic editors and about these tools, see Graphic editors.

42 User Guide
 Creating diagrams

Creating diagrams
The Diagrams drawing buttons access the graphic editor to create and edit diagrams. The Profiles
create a starting point structure for new projects and control which diagrams are available for those
projects. The available diagrams are represented as buttons on the toolbar across the top of the
Rational Rhapsody window.

To create a new diagram:

1. Choose Tools > Diagrams and select the type of diagram you want to create, or click the
diagram button at the top of the Rational Rhapsody window.

2. The Open window for the selected diagram displays. Highlight the portion of the project
with which the diagram will be associated.

3. Click New.

4. In the New Diagram window, enter the Name of the new diagram.

5. If you want to populate the new diagram automatically with existing model elements,
click the Populate Diagram check box.

6. Click OK.

Rational Rhapsody 43
Introduction to Rational Rhapsody

Tools for creating/opening diagrams

The Diagrams toolbar includes the following tools:

Diagram
Name Description
Button
Object Model This diagram shows the logical views of the static structure of the classes and
Diagram objects in an object-oriented software system and the relationships between them.
This diagram is available for the majority of profiles. Click this button to be able to
open an existing object model diagram or to create one.
Sequence This diagram shows the interactions between objects in the form of messages
Diagram passed between the objects over time. This diagram is available for the majority of
profiles. Click this button to be able to open an existing sequence diagram or to
create one.
Use Case This diagram shows the use cases of the system and the actors that interact with
Diagram them. This diagram is available for the majority of profiles and also the FunctionalC
profile. Click this button to be able to open an existing use case diagram or to create
one.
Component This diagram shows the dependencies among software components, such as library
Diagram or executable components. This diagram is available for the majority of profiles. Click
this button to be able to open an existing component diagram or to create one.
Deployment This diagram shows the run-time physical architecture of the system. This diagram is
Diagram available for the majority of profiles. Click this button to be able to open an existing
deployment diagram or to create one.
Collaboration This diagram describes how different kinds of objects and associations are used to
Diagram accomplish a particular task. This diagram is available for the majority of profiles.
Click this button to be able to open an existing collaboration diagram or to create
one.
Structure This diagram shows the architecture of the composite classes that define the model
Diagram structure. This diagram is available for the majority of profiles. Click this button to be
able to open an existing structure diagram or to create one.
Open A statechart defines the behaviors of individual classes in the system. This diagram
Statechart is available for the majority of profiles and also the FunctionalC profile. Click this
button to be able to create one a statechart.
Open Activity This diagram shows the lifetime behavior of an object, or the procedure that is
Diagram executed by an operation in terms of a process flow, rather than as a set of reactions
to incoming events. This diagram is available for the majority of profiles. Click this
button to be able to create an activity diagram.
Panel Diagram This diagram provides you with a convenient way to demonstrate a user device.
During animation or Webify, you can use a panel diagram to activate and monitor
your user application. This diagram is available for Rational Rhapsody in C, Rational
Rhapsody in C++, and Rational Rhapsody in Java projects. Click this button to be
able to open an existing panel diagram or to create one.
Build Diagram This diagram shows how the software is to be built. This diagram is primarily
associated with the FunctionalC profile. Click this button to be able to open an
existing build diagram or to create one.

44 User Guide
 Creating diagrams

Diagram
Name Description
Button
Call Graph A call graph shows the relationship of function calls as well as the relationship of
data. This diagram is primarily associated with the FunctionalC profile. Click this
button to be able to open an existing call graph or to create one.
File Diagram This diagram shows how files interact with one another (typically how the #include
structure is created). This diagram is primarily associated with the FunctionalC
profile. Click this button to be able to open an existing file diagram or to create one.
Message This diagram shows how the files functionality might interact through messaging
Diagram (synchronous function calls or asynchronous communication). This diagram is
primarily associated with the FunctionalC profile. Click this button to be able to open
an existing message diagram or to create one.
Open Flowchart For a function or class the chart, a flow chart shows the operational flow and code
generation. This diagram is primarily associated with the FunctionalC profile. Click
this button to be able to open an existing flow chart.

Opening the main diagram

To open the diagram for an element in the browser, select the element and choose Tools > Main
Diagram. This is commonly used to see the diagrams associated with classes. If no diagram is
identified as the main diagram for the selected class, no diagram is displayed.

Locating in the browser

If you want to locate an element from a diagram in the Rational Rhapsody browser, select the
diagram element and choose Edit > Locate in Browser, click the Locate in Browser button, or
press Ctrl+L. The browser opens and highlights the intended element.

Rational Rhapsody 45
Introduction to Rational Rhapsody

Add new elements

To create elements for your project, use either the Edit > Add New submenu commands or
right-click a browser item and select the intended addition from the Add New submenu. The
options displayed on the submenu depend on the selected item in the browser or diagram. After
you create the element, you might need to define it further using the The Features window.

Add New > Event

This menu command creates an event, which is a specification of a significant occurrence that has
a location in time and space.

Add New > Interface

This menu command creates a set of operations that publicly define a behavior or way of handling
something so knowledge of the internals is not needed or interface. Component diagrams define
interfaces between components only.

Add New > Actor

This menu command creates an actor element for a use case diagram.

Add New > Tag

Tags add information to the model relating to the domain or platform. To create a tag using
the browser, select the element and choose Edit > Add New > Tag.

Add New > Use Case

Use cases represent the externally visible behaviors or functional aspects of the system, but the
content of use cases is not used for code generation. To create a use case in the browser, select a
package or other element that might contain a use case and choose Edit > Add New > Use Case.

Add New > Requirement

To add an intended feature, property, or behavior of a system component as a requirement,
right-click the component in the browser and select Add New > Requirement.

46 User Guide
 Add new elements

Add New > Flow Item

To describe the kinds of information that can be exchanged between objects, add a flow item to
represent either pure data, data instantiation, or commands (events). Flow items can represent
classes, types, events, relations, parts, objects, attributes or variables. To add the flow item, select
the element being represented and choose Edit > Add New > Flow Item.

Rational Rhapsody 47
Introduction to Rational Rhapsody

The Features window

The Features window enables you to edit the features of each element in the Rational Rhapsody
model. The Features window contains a number of tabs that are common to almost all types of
elements:

General tab

Description (see Creating hyperlinks on the Description tab)

Relations (see Define relations)
Tags (see Use tags to add element information)
Displaying a tab on the Features window in a stand-alone window

Open the Features window

To define and change model elements, use any of these methods to launch the Features window for
the element that needs to be modified:

Double-click an element in the browser (except a diagram).

Double-click an element on a diagram.
Right-click an element and select Features.
Select an element in the browser and press Alt + Enter. This is unavailable for a Rational
Rhapsody project within the Eclipse platform.
Select an element and choose View > Features. This is unavailable for a Rational
Rhapsody project within the Eclipse platform.
The Features window lists different fields depending on the element type.

Applying changes with the Features window

When you have made changes that need to be applied to the project, an asterisk (*) is displayed in
the title bar of the Features window. Use one of these methods to save the changes.

Press Ctrl + Enter.

Click the Apply button on the Features window.
Change focus to another window or tab.
Initiate an external activity, such as generating code, saving the project, or generating a
report.
To apply changes and close the Features window, click OK.

48 User Guide
 The Features window

Canceling changes on the Features window

To cancel changes made to the Features window, press the Esc key. Alternatively, you can close
the window without applying changes.

Note that changes cannot be canceled once they have been applied to the model.

General tab
The General tab of the Features window enables you to define the characteristics of the selected
element. The fields for the General tab vary depending on the characteristics of the selected
element. The most common fields on the General tab are as follows:

In the Name box you specify the name of the element.

You use the L button to open the Name and Label window to specify the label for the
element, if any. For information on creating labels, see Descriptive labels for elements.
In the Stereotype list you specify the stereotype of the element, if any. For information on
creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the Select

Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Default Package specifies a group for the selected element.

Properties tab
The Properties tab of the Features window displays the properties for the currently selected item
(selected in the browser or in a diagram) or all of the properties for a model (choose File > Project
Properties).

For more information about the Properties tab, see Rational Rhapsody properties.

Rational Rhapsody 49
Introduction to Rational Rhapsody

Pinning the Features window

The Features window can be “pinned” to a specific element to keep the information for that
element displayed while examining other features for your element.

To pin a Features window to an element:

1. Right-click an element in the browser or a diagram and select Features to open the
Features window for that element.

2. Click the Pin button (horizontal orientation) in the upper right corner of the window.
Note that the button changes to a vertical orientation to indicate that the window for
this element will now remain displayed.

In pinned mode, the features displayed in the pinned window remain displayed and accessible
from all of the window tabs even when a different element is selected. Therefore, you can display
and pin two or three Features windows to compare the information for the elements.

When you no longer need to see the features of the element displayed, you can click the Pin button
again to disconnect it from the element or simply close the window.

Hiding the buttons on the Features window

At the bottom of the Features window, there are three buttons: Locate, OK, and Apply.

To remove these buttons from view, right-click the title bar for the Features window and uncheck
Features Toolbar.

Docking the Features window

By default, the Features window is a floating window. It can be positioned anywhere on the
window, or docked to the Rational Rhapsody work area.

To dock the Features window in the Rational Rhapsody window, do one of the following actions:

Double-click the title bar of the Features window. The window will jump to the location
where it was last docked. To dock the window in a different location, click the title bar
and drag the window to the intended location.
Right-click the title bar and select Enable Docking by Drag to display a check mark and
drag the window to the intended location.

50 User Guide
 The Features window

Undocking the Features window

To undock the Features window, do one of the following actions:

Double-click the title bar of the Features window.

Click the title bar and hold down Ctrl while dragging to a new location.
Right-click the title bar and select Enable Docking by Drag to remove the check mark
and drag the window to the intended location. The window is no longer docked with the
main window.

Opening multiple instances of the Features window

You can open multiple Features windows in the Rational Rhapsody workspace. Using this
functionality, you can easily compare the features of two different elements and quickly copy text
from one Features window to another.

To open more than one Features window, right-click an element and select Features in New
Window.

When opened as a new window, the Features window remains focused on the same element, even
when you change the browser or graphic editor selection. Any changes made to that element from
another view (such as the browser or a diagram editor) are automatically updated in the Features
window. This enables you to keep track of the features for a particular element while working with
other parts of the model.

When you have an open Features window that is focused on a particular element, you can locate
that element in the browser by clicking the Locate button at the bottom of the window.
Alternatively, you can locate the item by selecting the Locate in Browser tool from the standard
toolbar.

Displaying a tab on the Features window in a stand-alone window

For each of the Features tabs, you have the option to display the information in a dockable
stand-alone window.

To do display a tab on the Features window in a stand-alone window:

1. Select an element in the Rational Rhapsody browser or in a diagram.

2. Choose the relevant menu item in the View menu, for example, View > Description.

Rational Rhapsody 51
Introduction to Rational Rhapsody

Docking a stand-alone window for a Features window tab

Once you have a stand-alone window open for a tab of the Features window (as well as the
Features window), you can dock it.

To dock a the Features window or a stand-alone window for one of its tabs:

1. Right-click the title bar for the window and select Enable Docking by Drag.
Notice that a check mark displays to the left of the command on the pop-up menu.

2. Drag the window to one of the borders or other docking locations in the Rational
Rhapsody window.
Notice that upon reaching one of these locations, the outline of the window changes to
reflect the area the window occupies when docked.

Note
When one of these windows is docked, it continues to display the information in the same
manner as it does when it is “pinned,” as described in Pinning the Features window.

Undocking a stand-alone window for a Features window tab

To undock a the Features window or a stand-alone window for one of its tabs, do one of the
following actions:

To undock without disabling the docking capability, drag the window to one of the
non-docking locations in the Rational Rhapsody window.
To disable docking and undock:
a. Right-click the title bar for the window and select Enable Docking by Drag.
Notice that the check mark to the left of the command no longer displays.

b. Drag the window anywhere in the Rational Rhapsody window.

52 User Guide
 The Features window

Hiding tabs on the Features window

If you normally do not use one of the tabs on the Features window for a particular metaclass, you
can hide it. To do this, you have to create a New Term stereotype that sets the
HideTabsInFeaturesDialog property to hide one or more tabs on the Features window. Then you
would apply this stereotype to a model element of that metaclass.

Note
This feature is used exclusively for elements with the New Term stereotype.
To hide one or more tabs on the Features window for a particular metaclass:

1. Display your model in Rational Rhapsody.

2. In the Rational Rhapsody browser, create a stereotype as a New Term.

a. To learn how to create a stereotype, see Stereotypes.

b. Be sure to select one metaclass in the Applicable To box and select the New Term
check box on the General tab of the Features window for your stereotype.

c. On the Properties tab for the stereotype, locate the

Model::Stereotype::HideTabsInFeaturesDialog property.

Rational Rhapsody 53
Introduction to Rational Rhapsody

d. Click the box to the right of the property name and type the names of the tabs,
separated by a comma, that you want to hide; for example,
Description,Relations,Tags.

Note: You cannot hide the General tab.

e. Click OK.

54 User Guide
 Hyperlinks

3. Apply the stereotype to a model element of the metaclass. For example, if you selected the
Class metaclass (in the Applicable To box on the General tab of the Features window for
the stereotype), then you can apply this stereotype (select it from the Stereotype
drop-down menu on the General tab of the Features window for the class) to any classes
you currently have in your model or any that you create.

Note: When you define a stereotype as a New Term, it is given its own category in
the Rational Rhapsody browser, and any elements to which this stereotype is
applied are displayed under this category.
If you want to display a previously hidden tab, delete the name of that tab from the list you entered
in the Model::Stereotype::HideTabsInFeaturesDialog property.

Hyperlinks
Rational Rhapsody supports both internal hyperlinks, which point to Rhapsody model elements,
and external hyperlinks, which point to a URL or file.

In addition, you can:

Use the DiffMerge tool to compare models to locate differences in diagrams and to merge
models that contain hyperlinks.
Note: You can edit a description that uses hyperlinks or RTF format in the DiffMerge
tool if it is from the left or right side of the comparison, but you cannot edit a
description from a merge.
Export hyperlinks using the Rhapsody COM API.
Note: You cannot create or modify hyperlinks using the COM API.
Report on hyperlinks using ReporterPLUS.
Find references to hyperlinks using the Show References feature.

Rational Rhapsody 55
Introduction to Rational Rhapsody

Create hyperlinks
You can create hyperlinks inside the description of an element, or with the Rational Rhapsody
browser.

A typical use for the Description tab of the Features window is to enter a description for whatever
Rhapsody element you currently have open. For example, if you have the Features window open
for a class, you can enter a detailed description for the class on the Description tab. You can do the
same on the Description tab for an attribute, an event, a package, and so on.

Note
Hyperlinks created in the Description are not model elements and can neither be viewed in
the browser nor accessed by the API.

Creating hyperlinks on the Description tab

To create hyperlinks on the Description tab:

1. Open the Features window for the element.

2. On the Description tab, right-click in the open field and select Hyperlink.

Note: If you want to replace pre-existing text with a hyperlink, select the text before
right-clicking.
3. On the Hyperlink window, specify the hyperlink text and target.

The Text to display group specifies the text for the hyperlink. The possible values
are as follows:
– Free text displays the specified text as the hyperlink text.
– Target name displays the full path of the target as the hyperlink text.
– Target label displays the label of the target as the hyperlink text. This option
is available only for internal hyperlinks that have labels.
– Tag value displays the value for the tag. Note that this value is available only
when you select a tag as the hyperlink target. For an example that uses this
field, see Using tag values in hyperlinks.
The Link target group specifies the target file, Web page, or model element. You
can specify the target by typing the target in the text field, using the list to select
the model element in the model, or clicking the Ellipses button to open a new
window so you can navigate to the target file.
Note: You can include a relative path in the hyperlink target. If you use a relative path,
the base directory is the one where the
<Project name>.rpy file is located.

56 User Guide
 Hyperlinks

4. Click OK.
The hyperlink is displayed on the Description tab as blue, underlined text. This type of
hyperlink is not displayed in the browser.

Creating hyperlinks on the Rational Rhapsody browser

To create a hyperlink in the browser:

1. Right-click the element to which you want to add the hyperlink and select Add New >
Relations > Hyperlink.
Rhapsody creates a hyperlink in the browser.

Note: Add New > Relations is the default menu command structure in Rhapsody. It
can be changed by users. This topic assumes that all defaults are in place.
2. Open the Features window for the new hyperlink.

3. Specify the hyperlink display text in the Text to display group.

4. Specify the hyperlink target in the Link target group by typing the path, using the
drop-down list, or using the navigation window.
5. Optionally, specify a stereotype or description.

6. Click OK.

The hyperlink is added to the Hyperlinks category under the owner element.

To improve readability, there are different icons for the different targets, such as the following
targets:

Word files
Classes
URLs
You can drag-and-drop hyperlinks from the Hyperlinks category of one element to that of another.
Similarly, you can copy hyperlinks from the Hyperlinks category of one element to that of
another by dragging-and-dropping and pressing Ctrl, or using the Copy and Paste shortcuts.

Rational Rhapsody 57
Introduction to Rational Rhapsody

Following a hyperlink
To follow a hyperlink, double left-click it. The corresponding file, window, or URL is displayed.

Alternatively, you can use the Open Hyperlink option in the menu.

Edit a hyperlink
You can edit a hyperlink using the Features window or from within the Description area,
depending on the type of hyperlink.

Note
You cannot rename a hyperlink directly from the browser. You must open the Features
window.
Use the Features window to change the features of the hyperlink, including its text display and
target.

A hyperlink has the following features:

Name specifies the name of the element. The default name is hyperlink_n, where n is an
incremental integer starting with 0.
Text to display specifies the text for the hyperlink. The possible values are Free text,
Target name, Target label, and Tag value. For more information on these options, see
Creating hyperlinks on the Description tab.
Link target specifies the target file, Web page, or model element.
Description describes the hyperlink.

Editing the hyperlink in the Description area

To edit a hyperlink in the Description area:

1. Open the Features window for the element.

2. On the Description tab, right-click the hyperlink in the text and select Edit Hyperlink.

3. In the Hyperlink window (see Creating hyperlinks on the Description tab), edit the link.
4. Click OK.

58 User Guide
 Hyperlinks

Using tag values in hyperlinks

You can display the value of a tag in a hyperlink.

To add a tag value to a hyperlink:

1. Wherever you want to create the hyperlink, right-click and select Features to open the
Features window.
2. On the Tags tab, use the Quick Add group to enter the name of the hyperlink and its
value. If the tag does not have a value, the value «empty» is displayed.

3. Click OK.

Changing the tag value

To change the value of the tag:

1. Click the tag value hyperlink or click the New button on the Tags tab to open this
Features window.

2. Replace the existing value with the new value.

3. Click OK.

Deleting a hyperlink
Delete a hyperlink using one of the following methods:

In the text area of the Description tab, right-click the link and select Remove Hyperlink,
or use the backspace key or Delete icon.
In the browser, select the hyperlink and select Delete from Model or click the Delete icon.

Hyperlink limitations
Note the following limitations:

You can select tags as hyperlink targets, which are available in the Rhapsody browser. For
example, if you have the tag color in a profile that is applicable to all classes, you cannot
see the tag color under a given class instance in the browser. The Rhapsody browser
shows only local or overridden tags; however, these tags are shown in the Tags tab of the
Features window for the class.
If you override a tag value in a package, the tag is considered to be local because it is tied
to that specific element. If you have a hyperlink to the local tag and subsequently delete
the tag, the reference will be unresolved.

Rational Rhapsody 59
Introduction to Rational Rhapsody

Create a diagram
This topic is for Eclipse users.

Besides being able to import a Rational Rhapsody project and all its diagrams, you can create
diagrams in the Rational Rhapsody Platform Integration.

Creating a diagram
This procedure is for Eclipse users.

To create a Rational Rhapsody diagram in Eclipse:

1. On the New Diagram window, select a diagram type from the drop-down list.

2. Enter a name for the diagram.

3. If available, select a location for the diagram from the drop-down list.
4. If available, if you want to populate the new diagram automatically with existing model
elements. Click the Populate Diagram check box.

5. Click Finish.

Create a Rational Rhapsody project

Besides being able to import a Rational Rhapsody project in the Rational Rhapsody Platform
Integration, you can create a Rational Rhapsody project.

Creating a Rational Rhapsody project

This procedure is for Eclipse users.

To create a Rational Rhapsody project:

1. On the New Rhapsody Project window, enter a name for your Rational Rhapsody project.

2. Optionally, enter a name for your first object model diagram.

3. Select the language for your project from the drop-down list.

4. If available, select the Rational Rhapsody project type from the drop-down list.

5. If you want to designate a location for your project other than your default location, clear
the Use default location check box and browse to your preferred location.

60 User Guide
 Import a Rational Rhapsody project

6. Click Finish.

7. If the directory for your project is not already created, click Yes when you are asked if you
want to create it.

Import a Rational Rhapsody project

Besides being able to create a Rational Rhapsody project in the Rational Rhapsody Platform
Integration, you can import an existing Rational Rhapsody project.

Importing a Rational Rhapsody project

This procedure is for Eclipse users.

To import a project:

1. On the Import window, browse to your select root directory.

2. Select the projects you want to import.

Click Select All to select all the projects listed.

Click Deselect All to clear the check boxes for all the selected projects.
Click Refresh to refresh your list.
3. If available, select your options selection:

With All Subunits. Select this radio button to load all units in the project,
ignoring workspace information. For information on workspaces, see Using
workspaces.
Without Subunits. Select this radio button to prevent loading any project units.
All project units will be loaded as stubs.
Restore Last Session. Select this radio button if you would like to load only those
units that were open during your last Rational Rhapsody session.
4. Click Finish.

Rational Rhapsody 61
Introduction to Rational Rhapsody

Import source code

Importing source code involves the Rational Rhapsody Reverse Engineering tool.

Importing source code

This procedure is for Eclipse users.

To import source code:

1. On the Importing Source Code window, click the Finish button.

2. On the message box that displays click Continue to open the Reverse Engineering
window.
3. See Reverse engineering legacy code.

Search window
This topic is for Eclipse users.

The Search window shows results from searches of your model. Note that this window might not
appear until you perform a search (for example, choose Search > Search and select the Rhapsody
tab). For more information about doing searches in Rational Rhapsody, see Searching models.

Graphic editors
This topic is for Eclipse users.

You can use the graphic editors to analyze, design, and construct the system using UML diagrams.
Diagrams enable you to observe the model from several different perspectives, like turning a cube
in your hand to view its different sides. Depending on its focus, a diagram might show only a
subset of the total number of classes, objects, relationships, or behaviors in the model. Together,
the diagrams represent a complete design.

Rational Rhapsody adds the objects created in diagrams to the Rational Rhapsody project, if they
do not already exist. Conversely, Rational Rhapsody removes elements from the project when they
are deleted from a diagram. However, you can also add existing elements to diagrams that do not
need to be added to the project, and remove elements from a diagram without deleting them from
the model repository.

For more information about the graphic editors, see Graphic editors.

62 User Guide
 Call stack and event queue

Call stack and event queue

This topic is for Eclipse users.

The call stack view describes the current stack of calls for the focus thread. The event queue view
describes the current state of the event queue for the focus thread.

Rational Rhapsody 63
Introduction to Rational Rhapsody

64 User Guide
 Classes and types

Classes provide a specification (blueprint) for objects, which are self-contained, uniquely
identified, run-time entities that consist of both data and operations that manipulate this data.
Classes can contain attributes, operations, events, relations, components, super classes, types,
actors, use cases, diagrams, and other classes. The Rational Rhapsody browser icon for a class is a
three-compartment box with the top, or name, compartment filled in. For an example of this icon,
see Defining the attributes of a class.

Creating a class
To create a class, in the Rational Rhapsody browser:

Right-click the Classes category to which you want to add a class and select Add New
Class.
Right-click a package and select Add New > Class.
Select a package and choose Edit > Add New > Class.
Rational Rhapsody creates a new class and names it class_n, where n is greater than or equal to 0.
The new class is located in the browser under the Classes category, and is selected so that you can
rename it.

For information on creating classes in OMDs, see Object model diagrams.

Class features
Use the Features window to define and modify a class. You can also use it to re-arrange the order
of attributes and operations, control the display of attributes and operations, create templates, and
so on. To open the Features window for a class, double-click it on the Rational Rhapsody browser,
or right-click it and select Features.

Rational Rhapsody 65
Classes and types

Defining the characteristics of a class

Use the General tab of the Features window to define the characteristics of a class.

On the General tab, you define the general features for a class through the various controls on the
tab.

In the Name box you specify the name of the element. The default name is class_n,
where n is an incremental integer starting with 0. To enter a detailed description of the
class, use the Description tab.
You use the L button to open the Name and Label window to specify the label for the
element, if any. For information on creating labels, see Descriptive labels for elements.
In the Stereotype list you select the stereotype of the element, if any. For information on
creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the Select
Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Note: The COM stereotypes are constructive; that is, they affect code generation.
In the Main Diagram list you specify the diagram (from the ones available) that contains
the most complete view of the class.
In the Concurrency drop-down list box you specify the concurrency. The possible values
are as follows:
– Active means the class runs on its own thread.
– Sequential means the class runs on the system thread.
In the Defined In drop-down list box you specify the owner for the class. Every class lives
inside either a package or another class.
Note: A class not explicitly drawn in a package belongs to the default package of the
diagram. If the diagram is not explicitly assigned to a package, the diagram
belongs to the default package of the project.
In the Class Type area you specify the class type. The possible values are as follows:
– Regular creates a class.
– Template creates a template. To specify the necessary arguments, use the
Template Parameters tab that displays once you select the Template radio
button. For more information, see Creating a template class.
– Instantiation creates an instantiation of a template. To specify the necessary
arguments, use the Template Instantiation tab that displays once you select
the Instantiation radio button. For more information, see Instantiating a
template class.

66 User Guide
 Class features

Note: To create an instance of a class, select the Instantiation radio button and select
the template that the instance is from. For example, if you have a template class
A and create B as an instance of that class, this means that B is created as an
instance of class A at run time.

Selecting nested classes in windows

Every primary model element is uniquely identified by a path in the following form:
<ns1>::<ns2>::...<nsn>::<name>

In this syntax, ns can be either a package or a class. Primary model elements are packages, classes,
types, and diagrams. Classes can contain only other classes, stereotyped classes (such as actors),
and types.

You can select a nested element in a window by entering its name in either of the following
formats:

<name> in <ns1>::<ns2>::...<nsn>
<ns1>::<ns2>::...<nsn>::<name>

Defining the attributes of a class

Attributes are the data members of a class. Rational Rhapsody automatically generates accessor
(get) and mutator (set) methods for attributes, so you do not need to define them yourself.

The Rational Rhapsody browser icon for attributes is a three-compartment class box with the
middle compartment filled in:

The icon for the Attributes category is black.

The icon for an individual attribute is red.

The icon for a protected attribute is overlaid with a key.

The icon for a private attribute is overlaid with a padlock.

Rational Rhapsody 67
Classes and types

The Attributes tab of the Features window contains a list of the attributes that belong to the class.
It allows you to perform the following tasks:

Add a new attribute.

To create a new attribute, either click the <New> row in the list of attributes, or click the
New button in the upper, right corner of the window. The new row is filled in with
the default values.
Modify an existing attribute.

To modify an attribute, you can use any of the following methods:

– Select the attribute and change the value name and/or change its parameters
from the drop-down list boxes.

– Select the attribute and click the open Feature Dialog button to open the
Features window for the attribute and make your changes there. You can also
double-click the attribute name or icon next to the name to open the Features
window.
Delete an attribute.
To delete an attribute from the model, select the attribute and click the Delete button .
View the attribute values.

To view the values for an attribute, open the Features window for it.
You can use the following keyboard shortcuts within an editable list:

Arrow keys to move between rows and columns.

Enter key to start or stop editing in a text box, or to make a selection in a combo box.
Insert key to insert a new element below the selected element.
Delete key to delete the selected element.
Esc key to cancel editing.

68 User Guide
 Class features

Defining the features of an attribute

When you click the Invoke Features window button or double-click an attribute, the Attribute
window opens. This window is also displayed when you select an attribute in the browser and
might have different options than shown in here.

On the General tab, you define the general features for a attribute through the various controls on
the tab.

In the Name box you specify the name of the attribute. The default name is attribute_n,
where n is an incremental integer starting with 0. To enter a detailed description of the
attribute, use the Description tab.
You use the L button to open the Name and Label window to specify the label for the
element, if any. For information on creating tables, see Descriptive labels for elements.
In the Stereotype list you specify the stereotype of the attribute, if any. For information on
creating stereotypes, see Stereotypes for information on creating stereotypes.
– To select from a list of current stereotypes in the project, click the Select
Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Note: The COM stereotypes are constructive; that is, they affect code generation.
In the Attribute type area you specify the attribute type. There are two ways to specify the
type:
– Select the Use existing type check box to select a predefined or user-defined
type or class. Use the Type list to select from among the Rational Rhapsody
predefined types, and any types and classes you have created in this project.
Or to define a new type, delete the value in the Type drop-down list box to
enable the Invoke Features window button and click it to open the Type
window.

For more information on creating types, see Composite types.

– Clear the Use existing type check box if there is no defined type. A
C++[Java] Declaration box displays in which you can give the attribute a
declaration appropriate for your language edition. See Modifying data types.
In the Visibility area you specify the type of access (visibility) for the accessor/mutator
generated for the attribute: Public, Protected, or Private.

When you generate code, each attribute is generated into three entities:
– The data member itself
– An accessor (get) method for retrieving the data value
– A mutator (set) method for setting the data value

Rational Rhapsody 69
Classes and types

Note: The visibility setting affects only the visibility of the accessor and mutator
methods, not of the data member itself. The data member is always protected,
regardless of the access setting.
In the Multiplicity box (displayed when appropriate) you specify the multiplicity of the
attribute. If this is greater than 1, use the Ordered check box to specify whether the order
of the reference type items is significant. The modifier choices are as follows:
– Constant specifies whether the attribute is read-only (check box is selected)
or modifiable (check box is cleared).
– Reference specifies whether the attribute is referenced as a reference, such as
a pointer (*) or an address (&) in C++.
– Static creates a static attribute, which belongs to the class as a whole rather
than to individual objects. See Initializing static attributes.
In the Initial Value box you specify the initial value for the attribute.

Launching a text editor

To access the text editor, click the Ellipses button . Throughout the Rational Rhapsody
interface, the Ellipses button opens a text editor.

Modifying data types

To create or edit a user-defined data type:

1. Open the Features window for the attribute.

2. In the Attribute type area, clear the Use existing type check box.

3. Type a declaration for the new type in the C++[Java] Declaration box using the proper
syntax. Note the following information:

You can omit the semicolon at the end of the line; Rational Rhapsody
automatically adds one if it is not present.
Substitute %s for the name of the type in the declaration. For example:
typedef unsigned char %s[100]
This translates to the following declaration in the generated code:
typedef unsigned char msg_t[100];
4. Add a description for the type on the Description tab.

5. Click OK.

Rational Rhapsody adds it to the Types category under the package to which the class belongs,
rather than under the class itself.

70 User Guide
 Class features

Initializing static attributes

If you select the Static check box on the Features window for an attribute, use the Initial Value
box to enter an initial value. You can open a text editor for entering initialization code by clicking
the Ellipses button associated with the box.

For information on code generation for static attributes, see Generating Code for Static Attributes.

Class operations
The Operations tab of Features window for a class enables you to add, edit, or remove operations
from the model or from the current OMD view. It contains a list of all the operations belonging to
the class.

Rational Rhapsody enables you to create sets of standard operations for classes and events. For
more information, see Using Standard Operations.

You can create the following types of operations:

Primitive operations

Receptions

Triggered operations

Constructors

Destructors

Rational Rhapsody 71
Classes and types

Primitive operations
A primitive operation is one whose body you define yourself instead of letting Rational Rhapsody
generate it for you from a statechart.

Creating a primitive operation

To create a primitive operation using the Features window for a class:

1. On the Rational Rhapsody browser, double-click a class to open its Features window.

2. On the Operations tab, either click the <New> row in the list of operations or click the
New button in the upper, right corner of the window and select PrimitiveOperation. The
new row is filled in with the default values.

3. By default, Rational Rhapsody names the new primitive operation Message_n, where n is
greater than or equal to 0. Type the new name for the operation in the Name column.

4. Change the other default values as necessary.

5. Click OK.

Alternatively, you can create a primitive operation through the use of the Rational Rhapsody
browser, as follows:

1. In the Rational Rhapsody browser, right-click the class, actor, operation, or use case node
to which you want to add the operation and select Add New > Operation. Alternatively,
you can select the item and choose Edit > Add New > Operation from the menu bar.

2. Rename the operation.

Defining the features of a primitive operation

The Features window for a primitive operation enables you to change the features for it, including
its return values, arguments, and modifiers. On the General tab, you define the general features for
a primitive operation through the various controls on the tab. Notice that the signature for the
primitive operation is displayed at the top of the General tab of the Features window.

In the Name box you specify the name of the element. The default name is Message_n,
where n is an incremental integer starting with 0. To enter a detailed description of the
operation, use the Description tab.
You use the L button to open the Name and Label window to specify the label for the
element, if any. For information on creating labels, see Descriptive labels for elements for
information on creating labels.

72 User Guide
 Class features

In the Stereotype list you specify the stereotype of the attribute, if any. For information on
creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the Select
Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Note: The COM stereotypes are constructive; that is, they affect code generation.
In the Visibility list you specify the visibility of the primitive operation: Public,
Protected, or Private.
In the Type drop-down list box you specify the operation type. For primitive operations,
this box is set to Primitive Operation. If this is a template class, select the Template
check box. To specify the necessary arguments for the template, use the Template
Parameters tab that displays once you select the Template check box. For more
information, see Creating a template class.
In the Returns area you specify the return type of a function.
– If the function will return a defined type, select the Use existing type check
box and select the return type from the Type drop-down list box that displays
once you select the check box. Or to define a new type, delete the value in the
Type drop-down list box to enable the Invoke Features window button and
click it to open the Type window.

For more information on creating types, see Composite types.

– If you want to use a type that is not defined, clear the Use existing type check
box. A C++[Java] Declaration box displays. Enter the code as you want it to
appear in the return statement. To access the text editor, click the Ellipses
button .
In the Modifiers area you specify the modifiers of the operation. The possible values are
Virtual, Static, Inline, Constant, or Abstract, but the available modifier types vary
according to the type of operation.

Receptions
A reception specifies the ability of a class to react to a certain event (called a signal in the UML).
The name of the reception is the same as the name of the event; therefore, you cannot change the
name of a reception directly. Receptions are displayed under the Operations category for the
class.

Rational Rhapsody 73
Classes and types

Creating a reception using the Features window

To create a reception using the Features window:

1. On the Rational Rhapsody browser, double-click a class to open its Features window.

2. On the Operations tab, either click the <New> row in the list of operations or click the
New button in the upper, right corner of the window and select Reception from the
pop-up menu. The new row is filled in with the default values.

3. Type the name of the reception in the Event box on the New Reception window. If
Rational Rhapsody cannot find an event with the given name, a confirmation box opens,
prompting you to create a new event. Click Yes to create a new event and the specified
reception.

4. Open the Features window for the new reception operation you just created and set its
other values as necessary.

5. Click OK.

Creating a reception using the browser

To create a reception using the Rational Rhapsody browser:

1. In the browser, right-click a class, actor, operation, or use case node and select Add New >
Reception. The New Reception window opens.

2. Type the name of the new reception and click OK.

3. The following action happens depending on what Rational Rhapsody finds:

If Rational Rhapsody finds an event with the specified name, it creates the new
reception and displays it in the browser.
If Rational Rhapsody cannot find an event with the given name, a confirmation
box opens, prompting you to create a new event. Click Yes to create a new event
and the specified reception.
Note the following information:

When you add a new reception with a new name to a class, an event of that name is added
to the package. If you specify an existing event name, the reception simply points to that
event.
Receptions are inherited. Therefore, if you give a trigger to a transition with a reception
name that does not exist in the class but does exist in its base class, Rational Rhapsody
does not create a new reception.

74 User Guide
 Class features

Reception features
The Features window for a reception enables you to change the features of a reception, including
its type and the event to which the reception reacts. On the General tab, you define the general
features for a reception through the various controls on the tab. Notice that the signature for the
reception is displayed at the top of the General tab of the Features window.

In the Name box you specify the name of the reception. The default name is event_n,
where n is an incremental integer starting with 0. To enter a detailed description of the
reception, use the Description tab.
If the Name box is inaccessible, click the L button to open the Name and Label window to
change the name, if any. For information on creating labels, see Descriptive labels for
elements.
In the Stereotype list you specify the stereotype of the attribute, if any. For information on
creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the Select
Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Note: The COM stereotypes are constructive; that is, they affect code generation.
In the Visibility list you specify the visibility of the reception (Public, Protected, or
Private), if available.
In the Type drop-down list box you specify the operation type. For receptions, this box is
set to Reception.
In the Event list you specify the event to which the reception reacts. To view or modify the
features of the event itself, click the Invoke Features window button.

Deleting receptions
You cannot delete receptions in the following cases:

The reception is used by the statechart of the class.

The reception is used by a derived statechart of a class that does not have its own
reception.

Triggered operations
A triggered operation can trigger a state transition in a statechart, just like an event. The body of
the triggered operation is executed as a result of the transition being taken. For more information,
see Triggered operations.

Rational Rhapsody 75
Classes and types

Constructors
Constructors are called when a class is instantiated, generally to initialize data members with
values relevant to that object.

Rational Rhapsody has the following constructor icons:

The Rational Rhapsody browser icon for a constructor is a red triangle

with a black arrow.
The icon for a protected constructor is overlaid with a key.

The icon for a private constructor is overlaid with a padlock.

Creating a constructor
To create a constructor:

1. Depending on if you want to use the Features window or the Rational Rhapsody browser:

On the Rational Rhapsody browser, double-click a class to open its Features

window and on the Operations tab, either click the <New> row in the list of
operations or click the New button in the upper, right corner of the window and
select Constructor.
On the Rational Rhapsody browser, right-click either the class or the Operations
category under the class and select Add New > Constructor.
Note: Alternatively, you can open this window by right-clicking the appropriate
element in a diagram and selecting New Constructor.
2. The Constructor Arguments window opens.

3. Click Add. The Argument window opens.

4. Type in a name for the new constructor and change the default values as necessary.
5. Click OK twice.

76 User Guide
 Class features

The new constructor is listed under the Operations category for the class in the Rational
Rhapsody browser.
.

Defining constructor features

The Features window enables you to change the features of a constructor, including its arguments
and initialization code. Double-click the constructor in the Rational Rhapsody browser to open its
Features window.

On this General tab, you define the general features for a constructor through the various controls
on the tab. Notice that the signature for the constructor is displayed at the top of the General tab of
the Features window.

In the Name box you specify the name of the constructor. The default name is the name of
the class it creates. To enter a detailed description of the constructor, use the Description
tab.
If the Name box is inaccessible, click the L button to open the Name and Label window to
change the name, if any. For information on creating labels, see Descriptive labels for
elements.
In the Stereotype list you specify the stereotype of the attribute, if any. For information on
creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the Select
Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Note: The COM stereotypes are constructive; that is, they affect code generation.
In the Visibility list you specify the visibility of the reception (Public, Protected, or
Private), if available. The default value is Public.

Rational Rhapsody 77
Classes and types

In the Initializer box you enter code if you want to initialize class attributes or super
classes in the constructor initializer. To access the text editor, click the Ellipses button .

For example, to initialize a class attribute called a to 5, type the following code:
a(5)

Note: In C++, this assignment is generated into the following code in the class
implementation file to initialize the data member in the constructor initializer
rather than in the constructor body:
//-------------------------------------------------------
// A.cpp
//-------------------------------------------------------
A::A() : a(5) {
//#[operation A()
//#]
};

Note: You must initialize const data members in the constructor initializer rather than
in the constructor body.

Adding initialization code

To enter code for any initializations that you want to perform in the constructor body rather than in
the constructor initializer, use the Implementation tab. You can create and initialize objects
participating in relationships within the body of a constructor. You can pass arguments to these
objects if they have overloaded constructors using, for example:
new relatedClass(3)
This code in the body of the class constructor calls the constructor for the related class and passes
it a value of 3. The related class must have a conversion constructor that accepts a parameter. The
constructor of the related class then performs its initialization using the passed-in value.

78 User Guide
 Class features

Destructors
A destructor is called when an object is destroyed, for example, to de-allocate memory that was
dynamically allocated for an attribute during construction.

Rational Rhapsody has the following destructor icons:

The Rational Rhapsody browser icon for a destructor is a tombstone

(RIP = Rest In Peace).
The icon for a protected destructor is overlaid with a key.

The icon for a private destructor is overlaid with a padlock.

Creating a destructor
To create a destructor, follow the instructions for Creating a primitive operation, but for the type,
select Destructor.

Modifying the features of a destructor

Use the Features window to change the features of a destructor including its visibility and
modifier.

On this General tab, you define the general features for a destructor through the various controls
on the tab.

In the Name box you specify the name of the destructor. By definition, destructors have
the same name as the class, preceded by a tilde (~) symbol. To enter a detailed description
of the reception, use the Description tab.
If the Name box is inaccessible, click the L button to open the Name and Label window to
change the name, if any. For information on creating labels, see Descriptive labels for
elements.
In the Stereotype list you specify the stereotype of the attribute, if any. For information on
creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the Select
Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Note: The COM stereotypes are constructive; that is, they affect code generation.
In the Visibility list you specify the visibility of the reception (Public, Protected, or
Private). By default, destructors are Public.

Rational Rhapsody 79
Classes and types

In the Modifiers area you specify the modifiers of the destructor. Select Virtual, if
wanted.

To type code for the body of the destructor, use the Implementation tab.

Define class ports

Use the Ports tab to create, modify, and delete class ports.

The Ports tab contains the following columns:

Name specifies the name of the port.

Contract specifies the contract of the port. For more information about contacts, see The
Port Contract tab. The possible values are as follows:
– Implicit means that the contract is a “hidden” interface that exists only as the
contract of the port.
– Explicit mean that the contract is an explicit interface in the model. An
explicit contract can be reused so several ports can have the same contract.
Multiplicity specifies the multiplicity of the port. The default value is 1.
Behavior specifies whether the port is a behavioral port, which means that the messages
of the provided interface are forwarded to the owner class. If it is non-behavioral, the
messages are sent to one of the internal parts of the class.
Reversed specifies whether the interfaces are reversed, so the provided interfaces become
the required interfaces and vice versa.
For instructions on how to use the interface on this tab to create, modify, or delete a port, see
Defining the attributes of a class.

For detailed information about specifying ports, see Ports.

Define relations
The term “relations” refers to all the relationships you can define between elements in the model
(not just classes); for example, associations, dependencies, generalization, flows, and links. (In
previous versions of Rational Rhapsody, the term referred to all the different kinds of
associations.)

The Relations tab lists all the relationships (dependencies, associations, and so on) the class is
engaged with.

The Relations tab contains the following columns:

Name specifies the name of the relation.

80 User Guide
 Class features

Type specifies the relation type (for example, Association End and Dependency).
Direction specifies the direction of the relationship (From or To).
From/To specifies the target of the relationship. For example the dependency
Dishwasher.AbstractFactory goes from the Dishwasher class to the
AbstractFactory.
Data specifies any additional data used by the relationship.

For example, if you have a port that provides the interface MyInterface, the Data column
would list Provided Interface.

For more information on relationships, see Associations.

Rational Rhapsody 81
Classes and types

Showing all relations for a class, object, or package in a diagram

To understand the full meaning or purpose of a class, Rational Rhapsody lets you create an object
model diagram that shows a class and its relations to all the other elements in a project.

Note that you can show the relations for a class, an object, and a package. You would use the same
procedure as noted below, except that you would select that particular element (for example, an
object) instead.

To show all the relations of a class:

1. Right-click a class in the Rational Rhapsody browser and select Show Relations in New
Diagram.

2. Notice the following information:

Rational Rhapsody created an object model diagram that shows all the relations
for the selected class.
Rational Rhapsody also named the new object model diagram from the name of
the class you selected and it created an Object Model Diagram category to hold
the new diagram within the package where the class resides.

82 User Guide
 Class features

Note the following information:

The Show Relations in New Diagram pop-up menu command is available for classes,
objects, and packages from the Rational Rhapsody browser as well as on a diagram. For
both the browser and on a diagram, you would right-click the element (for example, an
object) and select Show Relations in New Diagram.
Note: For a diagram you can select multiple elements (for example, two classes). Use
Ctrl+Click to make multiple selections and then right-click one of the selected
elements to open the pop-up menu and click Show Relations in New
Diagram.
The location of the new object model diagram created by Show Relations in New
Diagram depends on whether you started the command from the browser or a diagram:
– When started from the browser, Show Relations in New Diagram creates the
diagram in the same location as the selected element and places it in an
Object Model Diagram category (which Rational Rhapsody creates if the
category is not already available).
– When started from a diagram, Show Relations in New Diagram creates the
object model diagram in the same location in which the source diagram
resides.
The new object model diagram created by Show Relations in New Diagram will be
named the same name as the class, object, or package from which it was created. If there
is already an object model diagram with that name, a number will be appended to the
name (for example, Dishwasher_9).
See also Automatically populating a diagram.

Defining class tags

The Tags tab lists the available tags for this class. For detailed information on tags, see Profiles.

Defining class properties

The Properties tab lets you set and edit class properties and displays the definitions for individual
properties with their default values. The definition of an individual property displays at the bottom
of the Features window when a property is selected in the Property tab.

Rational Rhapsody 83
Classes and types

Adding a class derivation

A class derivation is modeled as a dependency relationship with a stereotype of <<derive>>. Code
is not generated from that relationship.

The <<derive>> stereotype specifies a derivation relationship among model elements that are
usually, but not necessarily, of the same type. A derived dependency specifies that:

The client might be computed from the supplier.

The mapping specifies the computation.
The client might be implemented for design reasons, such as efficiency, even though it is logically
redundant.

To create a class derivation:

1. Right-click the class for which you are creating a derivation and select Add New >
Relations > Derivation.

2. In the window, select from the Depends on drop-down menu. The items in the drop-down
menu are as follows:

Elements currently in the model.

Profiles for the development language, as defined in Opening an existing Rational
Rhapsody project.
<<Select>> displays another window with model browser to allow you to make a
selection that is not listed in the drop-down menu.
3. Make your selection and click OK. The selected element is then listed under the Class
Derivation in the browser.

84 User Guide
 Making a class an instance

Making a class an instance

To make a class an instance in an OMD, select the Instance tab in the Features window.

If the class represents an instance, select the This box is also an instance check box. This is
equivalent to giving the class an instance name in the OMD. If this box is checked, the following
boxes become active:

Instance Name specifies the name of the instance.

Multiplicity specifies the number (or range) of times to instantiate the class.

The multiplicity indicates the number of instances that can participate at either end of a
relation. Multiplicity can be shown in terms of a fixed number, a range, or an asterisk (*),
meaning any number of instances including zero.

Defining class behavior

To define the behavior of a class, you give it either a statechart or an activity diagram:

1. In the OMD, right-click the class

2. Select either New Statechart or New Activity Diagram.

For more information on these diagrams, see Statecharts or Activity diagrams.

Generating, editing, and roundtripping class code

Rational Rhapsody enables you to generate code and open a text editor for editing the generated
code directly from within an OMD. The following sections describe these tasks in detail.

Generating class code

To generate code for a single class:

1. Right-click the class and then select Generate.

2. If a directory for the configuration that the class belongs to has not yet been created,
Rational Rhapsody asks if you want to create the directory. The configuration directory is
under the component directory. Click Yes.

3. Rational Rhapsody creates the configuration directory and generates the class code to it.
An output window opens at the bottom of the Rational Rhapsody window for the display
of code generation messages.

Rational Rhapsody 85
Classes and types

Editing class code

To edit code once it has been generated, right-click the class and select Edit Code. By default, the
code generated for the class opens in the Rational Rhapsody internal code editor. If both a
specification and an implementation file were generated for the class, both files open, with the
specification file in the foreground.

To set Rational Rhapsody to open the editor associated with the file extension instead of the
internal code editor:

1. Select File > Project Properties.

2. Set the General::Model::ClassCodeEditor property to Associate.

3. Click OK.

Roundtripping class code

When generating code, Rational Rhapsody places all user code for method bodies and transition
code written in statecharts between special annotation symbols. The symbols are as follows:

Language Body Annotation Symbols

Ada --+[ <ElementType> <ElementName>
--+]
C /*#[ <ElementType> <ElementName> */
/*#]*/
C++ and Java //#[ <ElementType> <ElementName>
//#]

For example, the following Initialize() operation for the Connection class in the PBX sample
contains user code that was entered in the Implementation field of the Operation window. The user
code is placed between the annotation symbols when code is generated for the class:
void Connection::Initialize() {
//#[ operation Initialize()
DigitsDialed = 0;
Digits[0] = 0;
Digits[1] = 0;
Busy = FALSE;
Extension = 0;
//#]
}

86 User Guide
 Opening the main diagram for a class

You can edit the code between the annotation symbols in a text editor and then roundtrip your
changes back into the model. The roundtripped edits will be retained upon the next code
generation. This is how Rational Rhapsody keeps the code and the model in sync to provide
model-code associativity.

Note
Any text edits made outside the annotation symbols might be lost with the next code
generation. For more information, see Deleting Redundant Code Files.
To roundtrip code changes back into the model:

1. Edit the generated class code between the //#[ and //#] annotation symbols.

2. In the browser or diagram, right-click the class containing the code that you just edited and
select Roundtrip.

If you view the Implementation box of the specification window for the operation (or the statechart
for the class if you edited transition code), you can see that your text edits were added to the
model.

Opening the main diagram for a class

You can specify a main diagram for a class in the Features window. This is usually the diagram
that shows the most important information for a class. For example, in the PBX sample, the PBX
diagram is specified as the main diagram for the Connection class. The main diagram for a class
must be either an object model diagram (OMD) or a use case diagram (UCD).

1. In the OMD, right-click the class.

2. Select Open Main Diagram.

Display option settings

Rational Rhapsody allows a great deal of flexibility in how elements are displayed. Display
options relate to how the element name, stereotype, and compartments are displayed in the
diagram. For example, to change the display options for a class, right-click the class in the diagram
and select Display Options (or select it and choose Edit > Display Options). The Display options
for the selected class opens.

Rational Rhapsody 87
Classes and types

General tab display options

The first tab of the Display Options window enables you to set general display options, including
the class name and stereotype. The General tab contains the following controls:

Display name specifies how the class name is displayed. A class is always inside at least
one package, but the package can be nested inside other packages, and the class can also
be nested inside one or more classes. The class name displayed in the OMD can show
multiple levels of nesting in the class name.

The possible display options are as follows:

– Full path means the full path name and includes the entire class nesting
scheme in the following format:

<p1>::<p2>::..::<pn>::<c1>::<c2>::.. ::<classname> In this syntax,

p[n] are packages and c[n] are classes.
– Relative means the relative name that shows nesting of a class inside other
classes, depending on its context within the diagram. For example, if class A
contains class B, then inside of A, the relative name for B is B, but outside of A,
the relative name for B is A::B.
– Name only means this option displays only the class name without any path
information.
– Label means this option displays the label for the class.
Show Stereotype Label indicates whether or not to display the class stereotype as text at
the bottom of the class box between guillemet symbols (for example, «Interface»).
Show Compartment Label indicates whether or not to display the labels of available
compartments. If you check the box, you then select the compartment for which you want
the labels displayed from the list in the Available column of this window. Select your
selections and click the Display button to move them into the Displayed column.
Image View specifies how the image is displayed. Check the box “Enable Image View”
and either of the following options:
– Use Associated Image means this option uses the default Rational Rhapsody
provided image for the object selected in Rational Rhapsody.
– Select An Image means if this option is selected, Rational Rhapsody displays
the Image File Path for you to locate it on your computer and click OK.

88 User Guide
 Display option settings

Advanced opens the Advanced Image View Options window. See Advanced Image View
Options window
Ports specifies whether to show new ports and their interfaces.
Rational Rhapsody allows you to specify which ports to display in the diagram using the
Show New Ports functionality. For more information, see Ports.

Advanced Image View Options window

To open the Advanced Image View Options window, click the Advanced button on the General
tab of the Display Options window, when it is available. This window has the following options:

Select Image Only to display the just the image.

Select Structured to see the picture in a separate compartment below the name
compartment for the object.
Select Compartment to see the picture in a separate compartment of its own between the
object name compartment and bottom compartment.

Displaying attributes and operations

The Attributes tab in the Display options window enables you to select which, if any, attributes to
display in the diagram.

To specify which elements to displayed in the diagram:

1. Select the element in the All Elements list.

2. Click the Display button to move the element to the Shown in Diagram list.

3. Repeat for each element or simply click the All button to select all of the elements in the
list and display them.
4. You can move elements up and down in the Shown In Diagram list or remove them using
the other three buttons in this window.

5. Click OK.

Similarly, the Operations tab allows you to select which, if any, operations to display in the
diagram.

Rational Rhapsody 89
Classes and types

Removing or deleting a class

You can remove a class from the current view (diagram) or delete the class entirely from the
model. Removing a class from the view does not delete it from the model.

To remove a class from the diagram, right-click the class and select Remove from View.

To delete the class entirely from the model, do one the following actions:

Right-click the class, then select Delete from Model.

Select the class, then click Delete in the main toolbar.

Note
When you delete a class, all of its objects are also deleted.

Ports
A port is a distinct interaction point between a class and its environment or between (the behavior
of) a class and its internal parts. A port allows you to specify classes that are independent of the
environment in which they are embedded. The internal parts of the class can be completely
isolated from the environment and vice versa.

A port can have the following interfaces:

Required interfaces characterizes the requests that can be made from the class for a port
(via the port) to its environment (external objects). A required interface is denoted by a
socket notation.
Provided interfaces characterizes the requests that could be made from the environment
to the class via the port. A provided interface is denoted by a lollipop notation.
These interfaces are specified using a contract, which by itself is a provided interface. For more
information, see The Port Contract tab.

If a port is behavioral, the messages of the provided interface are forwarded to the owner class; if
it is non-behavioral, the messages are sent to one of the internal parts of the class. Classes can
distinguish between events of the same type if they are received from different ports.

Note
See the HomeAlarmwithPorts sample model (under <Rational Rhapsody installation
path>\Samples\CppSamples) for an example of a model that uses ports.

90 User Guide
 Ports

Partial specification of ports

If you specify ports without any contract (for example, an implicit contract with no provided and
required interfaces), Rational Rhapsody assumes that the port relays events using the code
generator. You could link two such ports and the objects would be able to exchange events via
these ports. However, Rational Rhapsody will notify you during code generation (with warnings or
informational messages) because the specification is still incomplete.

Considerations
Ports are interaction points through which objects can send or receive messages (primitive
operations, triggered operations, and events). Ports in UML have a type, which in Rational
Rhapsody is called a contract. A contract of a port is like a class for an object.

If a port has a contract (for example, interface I), the port provides I by definition. If you want the
port to provide an additional interface (for example, interface J), then, according to UML, I must
inherit J (because a port can have only one type). In the case of Rational Rhapsody, this
inheritance is created automatically once you add J to the list of provided interfaces (again, this is
a port with an explicit contract I). According to the UML standard, if I and J are unrelated, you
must specify a new interface to be the contract and have this interface inherit both I and J.

Implicit port contracts

Some found that enforcing a specification of a special interface as the contract for a port to be
artificial, so Rational Rhapsody provides the notion for an implicit contract. This means that if the
contract is implicit, you can specify a list of provided and required interfaces that are not related to
each other, whereas the contract interface remains implicit (no need to explicitly define a special
interface to be the contract for the port in the model).

Working with implicit contracts has pros and cons. If the port is connected to other ports that
provide and require only subsets of its provided and required interfaces, it is more natural to work
with implicit contracts. However, if the port is connected to another port that is exactly “reversed”
(see the check box in the Features window for the port) or if other ports provide and require the
same set of interfaces, it makes sense to work with explicit contracts. This is similar to specifying
objects separately from the classes, or objects with implicit classes in the case when only a single
object of this type or class exists in the system.

Rapid ports
Rapid ports are ports that have no provided and required interfaces (which means that the contract
is implicit, because a port with an explicit contract, by definition, provides a contract interface).
These ports relay any events that come through them. The notion of rapid ports is Rational
Rhapsody-specific, and enables users to do rapid prototyping using ports. This functionality is
especially beneficial to users who specify behavior using statecharts, without the need to elaborate
the contract at the early stages of the analysis or design.

Rational Rhapsody 91
Classes and types

Creating a port
To create a port in an object model diagram:

1. Click the Port button.

2. Click the class boundary to place the port. A text box opens so you can name the new port.

3. Type the name for the port, then press Enter to dismiss the box. Note that the port label
uses the convention portName{[multiplicity]}. For example:
a. p
b. p[5]

c. p[*]

The new port displays as a small square on the boundary of its class.

Alternatively, you can create a port in the following ways:

Use the Ports tab of the Features window for the class. For more information, see Define
class ports.
Right-click the class in the browser and then select Add New > Port.

92 User Guide
 Specifying the features of a port

Specifying the features of a port

As with all elements, you use the Features window to specify the features that define a port. The
Features window for a port includes five tabs: General, Contract, Relations, Tags, and
Properties.

The Port General tab

On the General tab, you define the general features for a port through the various controls on the
tab.

In the Name box you specify the name of the port. The default name is port_n, where n is
an incremental integer starting with 0. To enter a detailed description of the attribute, use
the Description tab.
You use the L button to open the Name and Label window to specify the label for the
element, if any. For information on creating labels, see Descriptive labels for elements.
In the Stereotype list you specify the stereotype of the port. For information on creating
stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the Select
Stereotype button .
– To sort the order of the selected stereotypes, click the Change Stereotype
Order button .
Note: The COM stereotypes are constructive; that is, they affect code generation.
In the Contract drop-down list box you specify the port contact. The list contains the
following possible values:
– <Implicit> means the contract is implicit.
– <New> enables you to define a new contract. If you select this value, Rational
Rhapsody displays a separate class Features window so you can define the
new interface.
– A list of classes with a stereotype that includes the word “interface.”
The arrow button next to the Contract box opens the Features window for the
contract. However, this button is disabled if the contract is implicit.

In the Multiplicity drop-down list box you specify the multiplicity of the port. The
multiplicity is included in the port label if it is greater than 1.
In the Visibility drop-down list box you specify the visibility for the port (Public,
Protected, or Private). The default value is Public.

Rational Rhapsody 93
Classes and types

In the Attributes area you specify the port attributes:

– If you select the Behavior check box, messages sent to the port are relayed to
the owner class. By default, the check box is cleared.
– If you select the Reversed check box, the provided interfaces become the
required interfaces, and the required interfaces become the provided
interfaces.

The Port Contract tab

The Contract tab enables you to specify the port contract. The contract specifies the provided and
required interfaces through relations to other interfaces.

There are two types of contract:

Explicit means the contract is an explicit interface in the model. An explicit contract can
be reused so several ports can have the same contract.
Implicit means the contract is a “hidden” interface that exists only as the contract of the
port.
For both provided and required interfaces, three buttons are available:

Add to add a new interface to the list of available interfaces. For provided interfaces, this
means that the contract inherits the selected interface; for required interfaces, this means
that the contract has a new dependency stereotyped «Usage» towards the interface.
Edit to open the Features window for the selected element so you can modify it.
Remove to remove the relation with the contract for the selected interface.
Note that if you selected the Reversed check box on the General tab, the bottom of the Contract
tab displays a message in red stating that the contract is reversed.

Specifying the port contract

To specify the contract information for the port:

1. To specify the provided interfaces, select the Provided folder icon, then click the Add
button in the top group box. The Add new interface window opens.

2. Either type in the new name of the interface, or use the list to specify the interface.

3. Click OK.

4. You return to the Contract tab, which now lists the provided interface you just specified.

5. To specify the required interface, click the Required folder, then select Add. The Add
New Interface window opens.

94 User Guide
 Specifying the features of a port

6. Specify the required interface and then click OK.

Note: If a provided interface (including the contract) has an association to another

interface, the other interface is a required interface.
7. Click OK.

Note: If an interface provided by a port inherits from another interface, then by

definition, the port also provides the base interface. This means that if you want
to remove the base interface from the contract, you must remove the
generalization between the two interfaces. (Before removing such an interface,
Rational Rhapsody will notify you that the generalization will also be
removed.)

Display options for ports

The owning class or object specifies whether ports and their interfaces are displayed. By default,
new ports and their interfaces are displayed.

To disable these default settings:

1. In the diagram, right-click the class or object that owns the port and select Display
Options.

2. Clear the Show Ports Interfaces or Show New Ports check box, as intended.

3. Click OK.

You can specify how the port name and stereotype are displayed using the Display Options
window for the port itself.

For more information on displaying ports, see Selecting which ports to display in the diagram.

Rational Rhapsody 95
Classes and types

The Tags tab

The Tags tab lists the tags available for the port. For detailed information on tags, see Profiles.

The Properties tab

The Properties tab lets you set and edit the properties that affect your model. The definition of
each property displays at the bottom of the Features window when you select a property in the list.

The following table shows the properties (under the ObjectModelGe subject) that control how
ports are displayed.

Metaclass Property Description

Class/Object ShowPorts Determines whether ports
are displayed in OMDs
ShowPortsInterfaces Determines whether ports
are displayed in OMDs
Port color Specifies the color used to
draw the port
Fillcolor Specifies the default fill
color for the port
name_color Specifies the default color
of the port name
UseFillcolor Specifies whether to use
the fill color for the port

Note that you cannot selectively show ports in diagrams, either all the ports are displayed, or none
of them are.

96 User Guide
 Viewing ports in the browser

Viewing ports in the browser

Ports are displayed in the browser under the appropriate class.

Connecting ports
To exchange messages using ports, you must specify links between their objects. You can use one
of these methods:

Draw a link to the ports as described in Links and associations.

Right-click each object individually and select Make an Object. This allows you to link
the two new objects via their ports without explicitly creating a link between the ports.
You can specify a link between a part (or a port of a part) to a port belonging to the enclosing class.

However, you cannot specify associations via ports nor specify a link between classes, even if the
ends are connected to ports.

Using rapid ports

Rational Rhapsody supports rapid ports: you can simply draw ports, connect them via links, create
a statechart, and the ports will exchange events without any additional information. In addition, if
a port is not connected to any of the internal parts for a class, the code generator assumes it is a
behavioral port and messages will be relayed to or from the class. In rapid mode, the classes must
be reactive because Rational Rhapsody assumes that events are exchanged.

Rational Rhapsody 97
Classes and types

Rapid ports would be useful in the following situations:

In component-based design. For example, when you have a class to be reused in different
systems and has a behavior of its own (not that of one of its parts) that provides and
requires the interfaces of the contract for the port.
The class has a statechart in which the triggers of the transitions are based on the ports
through which the events were received. In other words, because the statechart is able to
distinguish between the ports through which an event was sent, it could react differently
to the same events based on which port the event came from.

Note
Once you specify the contract on a port, you must specify the contract on all the ports that
are connected to it. Otherwise, the code generator will issue a warning that there is a
mismatch in the contracts and the links will not be created.
Rational Rhapsody uses the values of the following framework properties to implement the rapid
ports:

DefaultProvidedInterfaceName specifies the interface that must be implemented by the

“in” part of a rapid port.
DefaultReactivePortBase stores the base class for the generic rapid port (or default
reactive port). This base class relays all events
DefaultRequiredInterfaceName specifies the interface that must be implemented by the
“out” part of a rapid port
DefaultReactivePortIncludeFile specifies the include files that are referenced in the
generated file that implements the class with the rapid ports
Consider the following figure, which shows an OMD that uses rapid ports.

98 User Guide
 Using rapid ports

The following figure shows the statechart for the Ping class.

The following figure shows the statechart for the PongMachine part.

During animation, the two objects exchange evPing and evPong events.

Rational Rhapsody 99
Classes and types

Selecting which ports to display in the diagram

If you right-click a class and select Ports, the following options are available:

New Port creates a new port on the specified class.

Show All Ports shows all the ports that currently exist in the specified model class.
Hide Ports hides all the ports that are currently displayed by the specified model class.
However, ports that are created later will be displayed.
Using this show/hide functionality in conjunction with the Show New Ports display option for the
owning class, you can show and hide ports as intended to simplify your model. For more
information on display options for classes, see General tab display options.

If you set Show New Ports mode to on, each new port that is added to the class is also displayed in
the diagram class. Ports created before this graphic class, or while the Show New Ports feature is
off, are not synthesized in the diagram, unless they were created using the graphic editor New Port
option.

If Show New Ports mode is off, any ports created after disabling this mode will not be displayed.

Creating a new port for a class

To create a new port:

1. Right-click a class and select Ports.

2. Select New Port creates a new port on the specified class.

Showing all ports

To show all the ports in the diagram, select the Show New Ports check box in the Display Options
window for the owning class, and select Ports > Show All Ports for the class.

Showing new ports only

To show only new ports in the diagram, select the Show New Ports check box in the Display
Options window for the owning class, and select Ports > Hide Ports for the class.

Hiding all ports

To hide all ports in the diagram, clear the Show New Ports check box in the Display Options
window for the owning class, and select Ports > Hide Ports for the class.

100 User Guide

 Selecting which ports to display in the diagram

Deleting a port
To remove a specific port from a class, use the Delete from Model or Remove from View option
in the menu for the owning class.

Programming with the port APIs in C++

The following sections describe the APIs you use to program using ports. The topics are as
follows:

Basic API tasks

Intermediate-level tasks

Advanced-level tasks

Basic API tasks

This section describes the basic APIs used to exchange messages with and instantiate ports.

Note
The following example is not complete; it is simply a reference for the subsequent table of
API calls.
Consider the following example:

The following table shows the calls to use to perform the specified tasks.

Task Call
Call an operation. OUT_PORT(src)->f();
Send an event from a to b using the ports. OUT_PORT(src)->GEN(evt);
Listen for an event from port src to port evt[IS_PORT(mon)]/
mon. doYourStuff();

Rational Rhapsody 101

Classes and types

You could also use the OPORT macro, which is equivalent to OUT_PORT.

Communicating with ports with multiplicity

The following table shows the calls to use if the multiplicity of the ports is 10 and you want to
communicate with the ports using index 5.

Task Call
Call an operation. OUT_PORT_AT(src, 5)->f();
Send an event from a to b using the ports. OUT_PORT_AT(src, 5)->GEN(evt);
Listen for an event from port src to port evt[IS_PORT_AT(mon, 5)]/
mon. doYourStuff();

You could also use the OPORT_AT macro, which is equivalent to OUT_PORT_AT.

Intermediate-level tasks
This section describes the intermediate-level APIs used when programming with ports. You use
these APIs whenever the code generator cannot create the links on its own, including the following
cases:

An external source file is used to initialize the system and you must write the code to
create the links between the objects.
The port multiplicities are not definite (for example, *).
The port multiplicities do not match across the links. This could happen when ranges of
multiplicities are used (for example, 1..10).

Connecting objects via ports

If you are using an external application (such as the MFC GUI) where the links are created at run
time, you can link objects with ports specified by Rational Rhapsody using calls similar to the
following examples:
a.getSrc()->setItsJ(b.getMon()->getItsJ());
b.getMon()->setItsI(a.getSrc()->getItsI());
To link the objects:

1. Create a temporary package that creates the links for you.

2. Copy the .cpp file for the new package to the correct class.

3. Modify the code as needed.

102 User Guide

 Selecting which ports to display in the diagram

Linking objects via ports with multiplicity

Using the example in the previous API illustration if the multiplicity of both ports is 10, you would
link the objects as follows:
for (int i+0; i<10; ++1) {
a.getSrcAt(i)->setItsJ(b.getMonAt(i)->getItsJ());
b.getMonAt(i)->setItsI(a.getSRcAt(i)->getItsI());
}

Advanced-level tasks
This section describes the advanced-level APIs used when programming with ports. You use these
APIs when the code generator cannot determine how to instantiate the ports. This situation occurs
when the port multiplicity is *.

Creating ports programmatically

By default, ports are created by value. However, if at design time you do not know how many ports
there will be (multiplicity of *), you can create the ports programmatically.

For example, to instantiate 10 of the src ports, use the following call:
for (int i=0; i<10; ++1) {
// instantiate and add to the container of the owner
newSrc();
}

Linking behavioral ports to their owning instance

Similarly, if you do not know what the multiplicity of the behavioral port at design time, you can
specify it programmatically.

Behavioral ports are connected to their owning instance using the method connect[ClassName].
For example, to connect behavioral port p to its owner object a (of type A), use the following call:
a.getP()->connectA(a);
If the ports in previous API illustration are behavioral, you would use the following code:
for (int i=0; i<10; ++i) {
newSrc();
//hooks the class so it takes care of the messages
getSrcAt(i)->connectA(this);
}
For more efficiency, use the following code:
for (int i=0; i<10; ++i) {
newSrc()->connectA(this);

Rational Rhapsody 103

Classes and types

Port code generation in C

In C, code can be generated for the following types of ports:

Rapid ports (see Using rapid ports)

Standard ports where the provided and required interfaces contain only event receptions

Action language for sending events

The following macros are used for working with ports and events:

Generating and sending an event via a port:

– RiCGEN_PORT([pointer to port], [event])

Examples:
RiCGEN_PORT (me->myPort, myEvent())

For ports with multiplicity greater than one:

RiCGEN_PORT (me->myPort[2], myEvent())
Detecting the input port through which an event has been sent:
– RiCIS_PORT([pointer to port])

Examples:
RiCIS_PORT(me->myPort)
This returns True if the event currently being handled by the Rational
Rhapsody Developer for C Reactive (instantiated as me) was sent via the port
myPort.

For ports with multiplicity greater than one:

RiCIS_PORT(me->myPort[2])

104 User Guide

 Selecting which ports to display in the diagram

Port code generation in Java

The following operations are used for working with ports and events in Java:

Calling an operation:
– for port called MyPort and operation called myop:
getMyPort().myop();
– for port called MyPort, operation called myop, and multiplicity greater than 1:
getMyPortAt(port index).myop(), for example,
getMyPortAt(2).myop();
Generating and sending an event via a port:
– for port called MyPort and event called evt:
getMyPort().gen(new evt());
– for port called MyPort, event called e2, and multiplicity greater than 1:
getMyPortAt(port index).gen(new e2()), for example,
getMyPortAt(2).gen(new e2());
Detecting the input port through which an event has been sent:
– for port called MyPort:
isPort(getMyPort())
– for port called MyPort, and multiplicity greater than 1: isPort(getMyPort(port
index)), for example,
isPort(getMyPort(3))

Rational Rhapsody 105

Classes and types

Composite types
Rational Rhapsody enables you to create composite types that are modeled using structural
features instead of verbatim, language-specific text. In addition, Rational Rhapsody includes
classes wherever types are used to increase the maintainability of models: if you change the name
of a class, the change is propagated automatically throughout all of the references to it.

To create a composite type:

1. Right-click a package or the Types category, then select Add New > Type.

2. Edit the default name for the type.

3. Open the Features window for the new type. The Type window opens.

4. If wanted, specify a stereotype for the type.

5. Specify the kind of data type using the Kind list. The possible values are as follows:

a. Enumeration specifies the new type is an enumerated type. Specify the enumerated
values on the Literals tab. For more information, see Creating enumerated types.
b. Language specifies the new type is a language-specific construct. This is the default
value. For more information, see Creating language types.

c. Structure specifies the new type is a structure, which is a data record. For more
information, see Creating structures.

d. Typedef specifies the new type is a typedef. For more information, see Creating
Typedefs.

e. Union specifies the new type is a union, which is an overlay definition of a data
record. For more information, see Creating unions.

See the appropriate data type to continue the creation process.

The following table shows the mapping of composite types to the different languages.

Type Kind Ada C and C++ Java

Language As in previous versions As in previous As in previous
versions versions
Structure Not supported struct1 N/A
Union Not supported union N/A
Enumeration Enumeration types enum N/A
Typedef Subtypes (in simple typedef N/A
cases) or subtype

106 User Guide

 Composite types

1. The generated struct is a simple C-style struct that contains only public data members.

Code generation analyzes the types to automatically generate:

Dependencies in the code (#include)

Type descriptions
Field descriptions

Each field in a structure and union has an attribute annotation.

Creating enumerated types

If you selected Enumeration as the Kind, continue the creation process as follows:

1. On the Literals tab, select the <New> line, and then type the name for the enumerated
value.

2. Repeat for each value of the enumerated type.

The following figure shows values for an enumerated type.

3. Click OK.

Rational Rhapsody 107

Classes and types

Creating language types

If you selected Language as the Kind, continue the creation process as follows:

1. On the Declaration tab, type the declaration statement in the Declaration text box. Use
the expression %s as a placeholder for the type name in the declaration.

The following figure shows an example of a type of kind Language.

2. Click OK.

Using %s
The Rational Rhapsody code generator substitutes %s in type declarations with the type name. This
automates the update of declarations when you rename a type.

To escape the %s characters, type a backslash (\) character before the %s. For example:
#define PRINT printf("\%s\n", myString())

108 User Guide

 Composite types

Creating structures
If you selected Structure as the Kind, continue the creation process as follows:

1. On the Attributes tab, select the <New> line, and then type the name for the member.

2. Use the Type list to select the type of the member. Note that the type can be another
composite type.

3. Repeat Steps 1 – 2 for each structure member.

The following figure shows an example of a type of kind Structure.

4. Click OK.

Note
Bit fields (for example, int a :1) are not supported. You can model them using language
types. For more information, see Creating language types.

Rational Rhapsody 109

Classes and types

Creating Typedefs
If you selected Typedef as the Kind, continue the creation process as follows:

1. On the Details tab, specify the typedef in the Basic Type box, or use the list to select the
type. Note that the Basic Type cannot be an implicit type.

Note: If you select a type defined within the model, the arrow button next to the Basic
Type box is available. Click the arrow button to open the Features window for
that class.
2. Specify the multiplicity in the Multiplicity box. The default value is 1.

Note: If the multiplicity is a value higher than 1, the Ordered check box is available.
Click this check box if the order of the reference type items is significant.
3. If the typedef is defined as a constant (is read-only, such as the const qualifier in C++),
enable the Constant check box; if the typedef is modifiable, leave the check box
disabled (empty).

4. If the typedef is referenced as a reference (such as a pointer (*) or a C++ reference (&),
enable the Reference check box.

The implementation of the reference is set by the property

<lang>_CG::Type::ReferenceImplementationPattern. See the definition of this
property in the Features window.

5. Click OK.

Creating unions
If you selected Union as the Kind, continue the creation process as follows:

1. On the Attributes tab, select the <New> line, then type the name for the member.

2. Use the Type list to select the type of the member. Note that the type can be another
composite type.

3. Click OK.

Note
Ada variant record keys and conditions are not supported.

110 User Guide

 Composite types

Properties
The following table lists the properties that support composite types.

Subject and Metaclass Property Description

CG subject
Attribute/Type Implementation The Implementation property enables
you to specify how Rational
Rhapsody generates code for a given
element (for example, as a simple
array, collection, or list). (Default =
Default)
When this property is set to Default
and the multiplicity is bounded (not *)
and the type of the attribute is not a
class, code is generated without
using the container properties (as in
previous versions of Rational
Rhapsody).
Note that Rational Rhapsody
generates a single accessor and
mutator for an attribute, as opposed
to relations, which can have several
accessors and mutators. In smart
generation mode, a setter is not
generated when the attribute is
Constant and either:
• The attribute is not a Reference.
• or The multiplicity of the attribute
is 1.
• or The CG::Attribute::
Implementation property is
set to EmbeddedScalar or
EmbeddedFixed.
<ContainerType> subject
<ImplementationType> Various properties Contain the keywords $constant
and $reference to support the
Constant and Reference modifiers
<ImplementationType> FullTypeDefinition Specifies the typedef
implementation template
<lang>_CG subject
Attribute MutatorGenerate Specifies whether mutators are
generated for attributes
Attribute/Type ReferenceImplementationPatt Specifies how the Reference option is
ern mapped to code
Class/Type In Specifies how code is generated
when the type is used with an
argument that has the modifier In

Rational Rhapsody 111

Classes and types

Subject and Metaclass Property Description

InOut Specifies how code is generated
when the type is used with an
argument that has the modifier
InOut
Out Specifies how code is generated
when the type is used with an
argument that has the modifier Out
ReturnType Specifies how code is generated
when the type is used as a return type
TriggerArgument Is used for mapping event and
triggered operation arguments to
code instead of the In, InOut, and
Out properties
Type EnumerationAsTypedef Specifies whether the generated
enum should be wrapped by a
typedef.
This property is applicable to
enumeration types in C and C++.
StructAsTypedef Specifies whether the generated
enum should be wrapped by a
typedef.
This property is applicable to
structure types in C and C++.
UnionAsTypedef Specifies whether the generated
union should be wrapped by a
typedef.
This property is applicable to union
types in C and C++.

112 User Guide

 Language-independent types

Language-independent types
Rational Rhapsody enables you to build static models using language-independent, predefined
types, with no dependency on the implementation language.

The types are defined in the following files (under <Rational Rhapsody installation
path>\Share\<lang>\oxf):

Ada, the RiA_Types package

C, the RiCTypes.h
C++, the rawtypes.h
Java, the types are converted during code generation, based on properties defined in the
PredefinedTypes package loaded by Rational Rhapsody (under <Rational Rhapsody
installation path>\Share\Properties\PredefinedTypes.sbs).
The following table shows the mapping between the predefined types and the language
implementation types.

Model Type Ada C C++ Java

RhpInteger integer int int int
RhpUnlimitedNatural long_integer long long long
RhpPositive unsigned unsigned unsigned int
int int
RhpPositive unsigned unsigned unsigned int
int int
RhpReal long_float double double double
RhpCharacter character char char char
RhpString string char* OMString String
RhpBoolean boolean RiCBoolea bool boolean
n
RhpVoid Used in procedure void void void
declaration only
RhpAddress address void* void* Object

Rational Rhapsody 113

Classes and types

When you create attributes or operations, these language-independent types are included in the
Types list.

Changing the type mapping

The file PredefinedTypes.sbs contains the set of predefined types included in Rational
Rhapsody. This file is opened automatically when you create a new model or open an existing one.

If you previously changed this file, you can merge your changes:

1. Open the model or create a new one.

2. Select File > Add to Model. The Add To Model window opens.

3. Navigate to <Rational Rhapsody installation path>\Share\Properties.

4. Set the Files of type box to Package (*.sbs).

5. Select the PredefinedTypes.sbs file.

6. Click Open.

114 User Guide

 Language-independent types

7. Because the package already exists in the model, a window opens so you can add the
package to the model under a new name, such as PredefinedTypes_new.

8. Click OK.
9. Change the property <lang>_CG::Type::LanguageMap to TBS.

10. Save the modified package.

11. Close the model.

12. Run DiffMerge on your original file and the new one, which is located in the <project
name>_rpy directory.

13. Add your changes to the .sbs file located in <Rational Rhapsody installation
path>\Share\Properties.

Note
The following behavior and restrictions apply to the language-dependent types.
In Rational Rhapsody in J, language-independent types are supported only as
modeling constructs. You cannot use them in actions or operation bodies.
This feature does not apply to COM and CORBA.

Changing the order of types in the generated code

Types are generated in code in the order in which they appear in the browser. This can be a
problem if one type depends on another that is defined later.

For example, you can define a type FirstType as:

typedef SecondType %s
Next, define a type SecondType as:
typedef int %s
These two types defined in this order would result in a compilation error. To avoid this kind of
error, you can control the order in which types are generated using the Edit Type Order in Code
window, which is accessible via the menu for the Types category for an individual package or a
class.

Rational Rhapsody 115

Classes and types

To edit the order of types:

1. Right-click the Types category (or a package or a class) and select Edit Type Order. The
Edit Type Order in Code window opens.

2. Select the type you want to move.

3. Click Up to generate the type earlier or Down to generate it later.

4. Click OK.

116 User Guide

 Using fixed-point variables

Using fixed-point variables

For target systems that do not include floating-point capabilities, Rational Rhapsody in C provides
an option to use fixed-point variables.

This is done by scaling integer variables so that they can represent non-integral values. Rational
Rhapsody uses the 2 factorial approach to achieve this. For example, setting the bit that usually
represents 2^0 to represent 2^-3 (.125).

For each such variable, the user specifies the word-size and the precision of the variable. The
specific steps involved are described in Defining fixed-point variables.

Defining fixed-point variables

The elements required for defining fixed-point variables are included in a profile called
FixedPoint. This profile contains:

Predefined types representing 8, 16, and 32-bit fixed-point variables: FXP_8Bit_T,

FXP_16Bit_T, FXP_32Bit_T. (These are the only types that can be used with fixed-point
operations.)
A “new term” stereotype, applicable to attributes, called FixedPointVar, with a tag called
FXP_Shift which is used to define the scale of the fixed-point variable.
The word-size is determined by the type chosen, while the shift to use is determined by the value
entered for the tag FXP_Shift.

The profile uses a file called FixedPoint.h, which contains:

Typedefs representing the predefined fixed-point variable types

Macros that are used for carrying out operations on fixed-point variables.

The file is “included” into the generated code where fixed-point variables are generated.

To define a fixed-point variable:

1. Add the FixedPoint profile to your project as a reference.

Note: The FixedPoint profile is added with Rational Rhapsody only if you selected
the Automotive add-on during installation.
2. In the browser, right-click the element that will contain the fixed-point variables and select
Add New > General Elements > FixedPointVar.

3. Name the new variable.

Rational Rhapsody 117

Classes and types

4. Open the Features window for the new variable, and for Type select one of the fixed-point
variable types (FXP_8Bit_T, FXP_16Bit_T, or FXP_32Bit_T). (If you do not see these
types in the list, click Select and locate the relevant type in the tree that is displayed.)

5. Set the shift to use by providing a value for the tag FXP_Shift (default value is 4). (The
variable that was created already has the Fixed-Point stereotype applied to it.)

Operations permitted for fixed-point variables

The following operations can be performed on fixed-point variables:

Arithmetic: addition, subtraction, multiplication, division

Assignment (=)
Relational operators (<, >, <=, >=, = =, !=)
To carry out the operations, you use the relevant macros that are contained in FixedPoint.h. For
example to add fixed-point variables, use the macro FXP_ASSIGN_SUM. (Note that some of the
macros in this file are macros that are called by the operation macros. These macros should not be
called directly.)

Restrictions on use of fixed-point variables

Keep the following points in mind when working with fixed-point variables:

The supported operations can only be performed on fixed-point variables, and not on the
result of fixed-point calculations. For example, these are not permitted:
FXP_ASSIGN_SUM(FXP_ASSIGN_SUM(varA,varB),varC).
Operations can be performed on fixed-point variables only. If you try to use one of the
operations with a combination of fixed-point and ordinary variables, compilation errors
will result.
The shift specified can range from 0 to (word size - 1). Rational Rhapsody does not check
that the shift you entered for the variable is within this range.
When calling a function that takes a fixed-point variable as an argument, make sure that
the variable provided to the function has the same fixed-point characteristics (word size
and shift) as the defined argument.
When calling a function that returns a fixed-point variable, make sure that the return value
is being assigned to a variable that has the same fixed-point characteristics (word size and
shift) as the defined return type.
Programmers must take into account that operations on fixed-point variables can result in
an arithmetic overflow.
Programmers must take into account that operations on fixed-point variables can result in
a loss of precision.

118 User Guide

 Using fixed-point variables

Fixed-point conversion macros

Rational Rhapsody provides the following macros for converting to/from fixed-point variables:

FXP2INT(FPvalue, FPshift) - Converts a fixed-point variable to an integer

FXP2DOUBLE(FPvalue, FPshift) - Converts a fixed-point variable to a double
DOUBLE2FXP(Dvalue, FPshift) - Converts a double to a fixed-point variable
These macros can be used in conjunction with the macros that require fixed-point variables as
arguments, for example:
FXP_ASSIGN_EXT(myFixedPointVar, FXP_16Bit_T, 4, DOUBLE2FXP(3.5, 1), 1);
The arguments provided represent:

Fixed-point variable to be initialized

FXP type of the variable to be initialized
FXP shift of the variable to be initialized
Initializing value in integer representation
Shift of the integer initializing number

Rational Rhapsody 119

Classes and types

Java enums
Rational Rhapsody allows use to include Java enums (introduced in Java 5.0) in your models.

Adding a Java enum to a model

To add a Java enum to your model, right-click the package to which you would like to add the
enum and select Add New > Enum.

Enums are displayed as their own category in the Rational Rhapsody browser.

Defining constants for a Java enum

To define constants for an enum:

1. Double-click the relevant enum in the browser to open its Features window.

2. Select the Enum Values tab.

3. Click <New> in the list.

4. Click the Name column to change the default name assigned by Rational Rhapsody.

5. Click the Value column to define the argument values that will be used to instantiate this
instance of the enum (if you are providing more than one argument, separate them with
commas).

6. Optionally, add comments for the constants you have defined.

7. Click OK.

After they have been defined, enum constants appear underneath the relevant enum in the browser.

120 User Guide

 Java enums

Note
Rational Rhapsody does not support the definition of anonymous classes that extend enum
constants.

Adding Java enums to an object model diagram

To add a Java enum to an object model diagram, drag the enum from the browser to the diagram.

Code generation
Rational Rhapsody generates Java code for the enums you have defined.

The reverse engineering feature does not support Java enums.

Creating Java enums with the Rational Rhapsody API

The following lines of code will add a new enum to the selected package, and define two constants
for the new enum:
Dim p As RPPackage
Dim c As RPClass
Dim a1 As RPAttribute
Dim a2 As RPAttribute

Set p = getSelectedElement
Set c = p.addNewAggr("Enum", "SampleEnum")
Set a1 = c.addNewAggr("EnumValue", "FIRST_CONSTANT")
Set a2 = c.addNewAggr("EnumValue", "SECOND_CONSTANT")

Rational Rhapsody 121

Classes and types

Template classes and generic classes

Rational Rhapsody allows you to include generic design elements in your models. Specifically,
you can:

Create and use template classes (C++)

Create and use generic classes (Java)
Create template functions (C++)
Create generic methods (Java)
The terminology used for these concepts differs slightly between C++ and Java. In this section, we
will use the UML terms template class and template operation to represent the generic elements in
both C++ and Java.

In general, the procedures described in this section apply to both C++ and Java. Where there are
language-dependent differences, these differences are noted.

Creating a template class

You can use a class to create a template class. In addition, some template parameters can be
specified as specific types and a specialized function to create a specialization or new class/
function with content that is unrelated to the original template.

Note that you can use the DiffMerge tool to locate and merge template information.

To create a class template:

1. Double-click the class in the Rational Rhapsody browser to open its Features window.

2. On the General tab, in the Class Type area, select the Template radio button.
Notice that the Template Parameters tab displays.

3. On the Template Parameters tab, click <New>.

4. Type a name to replace the default name that Rational Rhapsody creates as <class_n>.
For guidelines for these names, see Template limitations.

122 User Guide

 Template classes and generic classes

5. Accept the default type or select another one from the Kind list.

6. To add arguments for the template, click the Invoke Features window button to open
the Template Argument window. Note the following for the Template Argument window:

a. If you select the Use existing type check box, you can change the type and enter a
description. In C++, you can also provide a default value for the template argument.

b. If you clear the Use existing type check box, you can enter code that further refines
the argument type, for example a pointer to a type or an array of a certain type. When
entering code in the C++[Java] Declaration box, you can also see other arguments
that have been defined.
c. Click OK to close the Template Argument window and return to the Template
Parameters tab.

7. Add more templates as needed by clicking <New> on the Template Parameters tab.

8. To determine the argument order on the Template Parameters tab, use the Move Item Up
and Move Item Down buttons.

9. If there is a primary template that you want to use, select it in the Primary Template
drop-down list box. This box contains templates for which this class is a specialization. Its
parameters to be instantiated appear in the box below the Primary Template drop-down
list box.

You can define specialization parameters only if you select a template as a primary class.

Note: When you try to delete a template that has specialization, Rational Rhapsody
warns you that the template has references. If you do delete the template, such
specialization will generate an error when you check a model.

Rational Rhapsody 123

Classes and types

10. Click OK.

The template is listed in the browser in the Classes category.

Once you have created the template class, you can begin using it directly in your code.

You can create templates in other situations. For example, you can:

Re-use any type defined for a template parameter as a type within the template.
Use the template class as a generalization, as described in Using template classes as
generalizations.
Create an operation template, as described in Creating an operations template.
Create a function template, as described in Creating a functions template.
See also Instantiating a template class.

Using template classes as generalizations

To use a template class as a generalization:

1. Create a class in an OMD, or in the Rational Rhapsody browser.

2. Create the generalization by adding a super class in the browser or by drawing a

generalization connector from the new class to the template class.
3. Open the Features window of the generalization by using the context menu of the super
class in the browser or the generalization connector in the OMD.

4. On the Template Instantiation tab of the Features window, provide a value for each of
the arguments listed by selecting an item from the Value list or entering a new value.

Creating an operations template

To create an operation template:

1. Create an operation in a class.

2. Open the Features window for the operation.

3. On the General tab, select the Template check box.

Notice that the Template Parameters tab displays.

4. Set your template parameters for your operation on the Template Parameters tab. For
detailed instructions, see Creating a template class.
Once you have created the template operation you can begin using it in your code.

124 User Guide

 Template classes and generic classes

Creating a functions template

To create a functions template:

1. Create a function and open its Features window.

2. On the General tab, select the Template check box.

Notice that the Template Parameters tab displays.

3. Set your template parameters for your function on the Template Parameters tab. For
detailed instructions, see Creating a template class.
Once you have created the template operation you can begin using it in your code.

Instantiating a template class

To instantiate a template class:

1. Create a class in an OMD, or in the Rational Rhapsody browser.

2. Open the Features window for the class.

3. On the General tab, in the Class Type area, select the Instantiation radio button.
Notice that the Template Instantiation tab displays.

4. On the Template Instantiation tab, select a template from the Template Name
drop-down list box.

5. To view/modify the parameters for a template, double-click the template name or click the
Invoke Features window button to open the Template Instantiation Argument window.
Click OK to return to the Template Instantiation tab.

When code is generated, the template instantiation is represented by a typedef in C++ and by a
class in Java.

Rational Rhapsody 125

Classes and types

Code generation and templates

The creation of templates and specializations are supported in code generation. If both the
template and its specialization are in the same package, they are generated into the same file. In the
file, the template is generated before its specialization to ensure that the code runs as expected. A
check is added to warn that the template and template specialization are in different packages.

Note
If a nested class or attribute is marked as a template parameter, it is not generated.

Template limitations
The following limitations apply for templates:

If there is a template parameter named “T” in an operation/function, the user cannot assign
a class named “T” to the owner of the operation/function.
If there are more than one operation/function with a template parameter of the same name
under the same owner, renaming the created nested class renames all of the parameters
with this name.
For templates in a Java project, these are additional limitations:
– Wildcards are not supported.
– Bounded wildcards are not supported.
– Generic methods are not supported.

126 User Guide

 Eclipse platform integration

This subject describes the Rational Rhapsody Platform Integration, which lets software
developers work on a Rational Rhapsody project within the Eclipse platform. This integration is
currently available only for C, C++, or Java development in a Windows environment only and not
on Linux.

If you want to work in the Rational Rhapsody interface and use some Eclipse features, you can use
the Workflow Integration, which is the other Rational Rhapsody plug-in implementation. In this
integration, software developers work in the Rational Rhapsody product and open Rational
Rhapsody menu commands to use some Eclipse features. You can also navigate between the two
environments. This integration can be used for C, C++, and Java development in either Windows
or Linux environments. Both Eclipse and Rational Rhapsody must be open when you are using this
integration. For information about this implementation, see Rational Rhapsody projects.

Note
See the Rational Rhapsody installation instructions for Eclipse-specific installation and
set-up information.

Rational Rhapsody 127

Eclipse platform integration

Platform integration prerequisites

The following software needs to be used to create a fully functioning Eclipse platform integration
with Rational Rhapsody:

Eclipse Ganymede
CDT plug-in for C and C++ application development
JDT plug-in for Java development
Compilers required for the development language or languages you are using
Rational Rhapsody Developer edition (multi-language)
The Platform Integration of Rational Rhapsody for Eclipse requires a multi-language Rational
Rhapsody license.

Note
The stand-alone version of Rational Rhapsody and the Rational Rhapsody Platform
Integration within Eclipse both use the same repository so that you can switch between the
two interfaces if you want.

Confirming your Rational Rhapsody Platform

Integration within Eclipse
To confirm that you have the Rational Rhapsody Platform Integration within Eclipse:

1. In Eclipse, choose Help > About Eclipse SDK to open the About Eclipse SDK box.

2. You should see a Rational Rhapsody icon on the About Eclipse SDK box. If this icon does
not appear, you are not set up for the Rational Rhapsody Platform Integration. See the
Eclipse set-up instructions in the Rational Rhapsody installation instructions to set up for
this integration.

For descriptions of the areas in the Rational Rhapsody interface, see Rational Rhapsody Platform
Integration within Eclipse.

128 User Guide

 Rational Rhapsody Platform Integration within Eclipse

Rational Rhapsody Platform Integration within Eclipse

The standard Rational Rhapsody interface elements displayed in Eclipse have the same features as
in the stand-alone version except that the icons associated with a specific window are displayed at
the top of the window.

The Rational Rhapsody Platform Integration within Eclipse adds two Rational Rhapsody
perspectives on tabs in the upper right corner of the Eclipse IDE:

Rational Rhapsody modeling perspective

Rational Rhapsody Debug perspective

Rational Rhapsody perspectives in Eclipse

When you create a Rational Rhapsody project in Eclipse, the Rhapsody Modeling perspective is
automatically displayed and is set as the open Eclipse perspective.

If you have the tabs for perspectives displayed in the upper-right corner, you can click a tab to go
to another perspective.

Opening perspectives
To open a different perspective manually:

1. Choose Window > Open Perspective > Other.

2. On the Open Perspective window, select another perspective, such as Rhapsody Debug,
and click OK.

Rational Rhapsody 129

Eclipse platform integration

Rational Rhapsody modeling perspective

The Rational Rhapsody Modeling Perspective displays the main Rational Rhapsody interface
components, as illustrated in the following figure:

Browser (Model Browser tab in Eclipse)

Diagram Drawing Area
Output window and Features window

Rational Rhapsody Modeling Perspective tab

Drawing Area

Browser

Output Window

The Rational Rhapsody menu commands and drawing capabilities have been added to the Eclipse
code editing, interface customization, and other capabilities.

130 User Guide

 Rational Rhapsody Platform Integration within Eclipse

Rational Rhapsody Debug perspective

The Rational Rhapsody Debug perspective displays a number of windows. When you open the
Rational Rhapsody Debug perspective, the following windows might open in the Eclipse IDE:

Debug Tasks
Variables Problems
Animation Breakpoints Animation
Animation Manager Rhapsody Log
Console Check Model

Rational Rhapsody Debug Perspective tab

Developers can then use the Eclipse code level debugger and Rational Rhapsody design level
debugging with animation and breakpoints for a thorough and efficient debugging strategy.

Rational Rhapsody 131

Eclipse platform integration

Rational Rhapsody Eclipse support for add-on tools

The Eclipse Platform Integration of Rational Rhapsody supports for the add-on configuration
management tools and XMI file import and export capabilities.

Configuration management tools

The Rational Rhapsody Eclipse Platform Integration supports the common open source
configuration management (CM) tools, Concurrent Versions System (CVS) and
Subversion (SVN), in addition to these CM tools:

IBM Rational ClearCase

IBM Rational Synergy

XMI import and export

You can use the Rational Rhapsody XMI import and export facility with Eclipse projects. For
more information, see Using XMI in Rational Rhapsody development.

132 User Guide

 Eclipse projects

Eclipse projects
The Eclipse plug-in platform integration provides Rational Rhapsody and Eclipse features for
software developers.

Creating a new Rational Rhapsody project within Eclipse

To create a new Rational Rhapsody project within Eclipse:

1. In Eclipse, choose File > New > Project.

2. In the New Project window, select Rhapsody Project and click Next.

3. Type a name for your Rational Rhapsody project and select the language (C, C++, or Java)
from the list. In addition, you can type the name for your first object model diagram.

4. If you want to change the location of where you want to store your project, clear the Use
default location check box and then use the Browse button to navigate to another
location.
5. Click Finish on the New Rhapsody Project window when you are done defining your new
Rational Rhapsody project.

6. If the directory for your new project has not yet been created, click Yes when you are
asked if you want to create it.

Rational Rhapsody creates a new project in the work area you specified and opens the new project.

Opening a Rational Rhapsody project in Eclipse

To open an existing Rational Rhapsody project in Eclipse:

1. In Eclipse, choose File > Import to open the Import window.

2. Expand the Rhapsody folder, select Rhapsody Project, and then click Next.

3. On the Import window, click the Browse button to open the Browse for Folder window.

4. In the Browse For Folder window, select the folder that contains the Rational Rhapsody
project that you want to import, and then click OK.

5. On the Import window, select the project that you want to open and click Finish to open
the project in Eclipse.

Rational Rhapsody 133

Eclipse platform integration

Adding new elements

To add new elements to your project including diagrams, packages, and files:

1. With Eclipse Model Browser displayed, right-click an element for which you want to add
an element.

2. Select Add New > (element type) from the menu depending on what type of element you
selected. (See also Filtering out file types.)

The following figures show how you can add an element to your project. While this example
shows adding a package. The same method is true for other elements, such as diagrams, files,
actors, operations, and so on.

If you want to create a new package, right-click the project for a new main package or an existing
package to create a sub package and select Add New > Package. You can add other elements
(such an object, dependence, and a class) from the menu.

Filtering out file types

To prevent Eclipse from presenting unwanted Rational Rhapsody project file types when adding
files:

1. In Eclipse, choose Window > Preferences.

2. In the Preferences window, expand the Team section of the tree structure.

3. Select Ignored Resources to display the list of file extensions that can be set to be
ignored.

4. If the list does not contain the file types you want to filter out, click the Add Pattern
button.
5. On the Add Ignore Pattern window, type the file extension using the format shown in the
following figure and click OK to add the extension to Ignored Resources.

6. Using this method, you can enter the Rational Rhapsody *.dat, *.ehl, *.rpw, and *.vba
file extensions to Ignored Resources.

7. Click OK.

134 User Guide

 Eclipse projects

Exporting Eclipse source code to a Rational Rhapsody project

To export an Eclipse source code project from Eclipse to Rational Rhapsody:

1. With the model open in Eclipse, choose File > Export to open the Export window.

2. Expand the General folder, select File System, and then click Next.

3. In the File System view of the Export window, in the list in the left box:

Select the top-level project to select everything in the project, or

Select a subfolder folder to select only those items in that subfolder.
Note: You can select specific files to export from the list on the right. You can click
the Filter Types button to select specific file extensions to be exported.
4. Use the Browse button to navigate to a location directory for the exported files.

Rational Rhapsody 135

Eclipse platform integration

5. Select any of the Options that apply to this operation.

6. Click Finish to complete the export operation.

Note: If any problems were encountered during the operation, an Export Problems
message box displays. Click the Details button for more information.
7. To see your exported files, go to the location directory for your exported files.

Importing Rational Rhapsody units

To import Rational Rhapsody units into Eclipse:

1. In Eclipse, set the project for which you want to import units as the active configuration.
Right-click the project and select Set as Active Project.

2. Choose File > Import to open the Import window.

3. Expand the Rhapsody folder, select Rhapsody Unit, and then click Next.

4. In the Add to Model window, you can select a single file type (unit type) that you want to
import by using the Files of Type list or you can select the Rational Rhapsody project
(.rpy) to select all of the units in the project:

5. Click Open.

6. In the Add To Model From Another Project window, select the units you want and make
your applicable selections to the Add Subunits and/or Add Dependents check boxes,
and As unit or As reference radio buttons.

7. Click OK.

8. After the import is completed, a window displays the status of the import. Click Finish.

Importing source code (reverse engineering)

To import source code:

1. In Eclipse, set the project and the component as the active configuration.

a. Right-click the project and select Set as Active Project.

b. Right-click the component and select Set as Active Component.

2. In your Eclipse project, choose File > Import to open the Import window.

3. Expand the Rhapsody folder, select Source Code, and then click Next.

136 User Guide

 Eclipse projects

4. When the message window opens, confirm that you want to launch the Rational Rhapsody
Reverse Engineering interface, click Finish.

5. When asked to confirm that you want the reverse engineered code to be saved to the active
component and configuration, click Continue.

6. On the Reverse Engineering window, click Add Files or Add Folder to add items to be
reverse engineered.

7. After selecting the items to reverse engineer, click Start.

Note: You have a choice of a flat view or a tree view for the selected items. To toggle
between the views, click the Flat View button or the Tree View button .
8. Confirm that you want to continue with the reverse engineering process, click Yes.

9. Click Finish. The reverse engineering messages display in the Rhapsody Log window.

For more information about reverse engineering, see Reverse engineering.

Search and replace in models

The Rational Rhapsody search facility is available to use in Eclipse for these operations:

Perform standard search-and-replace operations

Search for the following types:
– unresolved elements in a model
– unloaded elements in a model
– units in the model
– both unresolved elements and unresolved units
Work with the search results
For more detailed instructions for the Rational Rhapsody Search and Replace facility, see Search
and replace facility.

Rational Rhapsody 137

Eclipse platform integration

Accessing the Rational Rhapsody search facility in Eclipse

To access Rational Rhapsody search in Eclipse:

1. With your Rational Rhapsody model open in Eclipse, choose Search > Search to open the
Search window. (You can also right-click an element in the model browser and select
Search.)

2. For the Rational Rhapsody search facility, click the Rhapsody tab. (You can also
right-click an element on the model browser and select Search inside.)

Customize the search criteria

In the Rational Rhapsody search facility you can use any of the standard search facilities. You can
also customize your search using the following buttons.

Exact string allows a non-regular expression search. When selected, the search looks for
the string entered into the search field (such as char*).
Wildcard allows wildcard characters in the search field such as * and produces results
during the search operation that include additional characters. For example, the search
*dishwasher matches class dishwasher and attribute itsdishwasher.
Regular Expression allows the use of Unix-style regular expressions. For example,
itsdishwasher can be located using the search term [s]dishwasher.

138 User Guide

 Eclipse projects

Search results display

The search results display in the Search tab of the Eclipse output window.

Working with search results

After locating elements using the Search facility, you can perform the following operations in the
Search window:

Sort items
Check the references for each item
Delete
Load
To sort the items in the list, click the heading for the column to sort according to information in
that column.

To work with an item located in the search:

1. Double-click an item in the list to open the its Features window and highlight its location
on the model browser.

2. Make any required changes from these entry points.

Rational Rhapsody 139

Eclipse platform integration

Generate and edit code

You can check your model, generate code, and edit the resulting code using Eclipse facilities. For
detailed instructions describing Rational Rhapsody code generation, see Basic code generation
concepts.

Checking the model

To launch the check model process, use one of these methods:

Choose Tools > Check Model and select one of these options:
– <name of active configuration>
– Selected Elements
– Configure
Right-click the active configuration and select Check.
The results display in the Check Model tab of the Output window.

As with search results, you can double-click an item on the Check Model tab to open the Features
window for the item and highlight it in the model browser.

140 User Guide

 Generate and edit code

Generate code
Rational Rhapsody uses an Eclipse IDE project for code generation. Before you can generate code,
you must perform the following tasks:

Create an Eclipse IDE project

Associate the Rational Rhapsody Eclipse configuration with the Eclipse IDE project

Creating an Eclipse IDE project

To create an IDE project to use for Rational Rhapsody code generation:

1. In the model browser, right-click an Eclipse configuration and select Create IDE Project.

2. If you have an existing Eclipse project in your work area, that project is listed in the
Existing Project list. However, you need to create a special Eclipse IDE project, so you
should select the New Project radio button.

3. Click Finish.
4. In the New Project window, select the project type based on your environment.

5. Click Next.

6. Enter a project name on the Project window and click Next.

7. If necessary, make a configuration selection on the Select Configurations window, and
then click Finish.

8. If your project type selection is different from your current perspective, an Open
Associated Perspective window opens to give you an opportunity to switch perspectives;
click Yes. If you want to keep using your currently active perspective, click No.

Rational Rhapsody 141

Eclipse platform integration

Generating code
After setting up the IDE project to receive the generated code, choose Code Generator >
Generate and one of these options:

<Active Configuration> (In the following figure, the active configuration is called GUI.)
Selected classes
<Active Configuration> with Dependencies
Entire Project
The system generates the requested code and displays messages in a log file.

Note: To show a complete log report, the following figure shows a very short report.
Typically, especially for the first code generation, there might be more
messages for each group (for example, the listing of code generated might be
longer).

142 User Guide

 Generate and edit code

Selecting Dynamic Model-Code Associativity

Rational Rhapsody lets you work in the model or code and maintain synchronization between each
so that changes in one are reflected in the other automatically. This is called Dynamic Model-Code
Associativity (DMCA).

To select the DMCA option you want to use:

1. Choose Code Generator > Dynamic Model Code Associativity.

2. From the submenu, select one of these commands:

Bidirectional changes made to the code or model are synchronized with the other.
Roundtrip changes made in the code are automatically synchronized with the
model.
Code Generation changes made in the model are updated in the code
automatically.
None turns off DMCA.

Edit code
You can edit your Rational Rhapsody code using the Eclipse editor.

Launching the Eclipse code editor from the browser or diagram

To display generated code for a specific element in the code editor:

1. In the model browser, right-click an item and select Edit Code to launch the
corresponding source code in the Eclipse code editor.

2. On the Eclipse code editor, highlight any items of interest and right-click to display the
editing menu.

Editing code from a diagram element

To launch the Eclipse code editor from a diagram element:

1. Open the diagram.

2. Right-click an item in the diagram and select Edit Code.

3. The Eclipse code editor opens.

Rational Rhapsody 143

Eclipse platform integration

Locating an element in the browser from the editor

If you are editing code and need to see an item in the project, usually in the model browser:

1. Highlight the item in the code.

2. Right-click and select Show in and then select one of the options. The option listed on this
submenu are controlled by the type of project displayed. For example, this option list is
for a C++ project:

Model Browser
C/C++Projects
Outline
Navigator

Viewing code associated with a model element

To see the code automatically for a selected model element:

1. Click the Link with Editor button located at the top of the Eclipse model browser.

2. Click an item in the model browser and notice that the code for the item is immediately
displayed and highlighted in the Eclipse code editor.

144 User Guide

 Build, debug, and animate

Build, debug, and animate

After checking your model and generating code, you can build your project.

Building your Eclipse project

You can use any of these methods to build your Eclipse project:

In the model browser, right-click the active configuration for your Eclipse project and
select Build Configuration.
Choose Project > Build Automatically to build from Eclipse using Java or C/C++ build
tools.
Select an element or group of elements in the model browser and choose the Project menu
to display this menu and select a build option.

Rational Rhapsody 145

Eclipse platform integration

Debugging your Eclipse project

After you have built your project, you can use the Eclipse debugging facilities with the Rational
Rhapsody Debug perspective. Choose the Run menu and then any of the debugging tools you
usually use in Eclipse. The External Tools window provides access to programs used to create,
manage, and run configuration you built project.

Rational Rhapsody animation in Eclipse

When running animated Rational Rhapsody applications, Eclipse switches to the Rhapsody Debug
perspective. You can debug an animated application using both Rational Rhapsody Animation
functionality and Eclipse Debugging tools.

For detailed instructions, see Animation.

146 User Guide

 Build, debug, and animate

Preparing for animation

Before you can begin animation, you must prepare for it:

1. In the model browser for the project, expand the Components folder.

2. Right-click the configuration you want to animate in the configuration folder and open the
Features window.

3. On the Settings tab, in the Instrumentation Mode box, select Animation.

4. Click Apply.

5. Right-click the configuration you want to animate in the configuration folder and select
Generate Configuration.

Run animation
Eclipse displays the Animation Manager window with Call Stack and Event Queue and an
Animation toolbar (at the top of the Animation Manager window, as shown in the following
figure) to perform all of the Rational Rhapsody standard animation tasks, watch the animation, and
note the messages on the Animation Log tab.

Rational Rhapsody 147

Eclipse platform integration

Debug animated applications

You might want to use the animated applications for debugging. The Java example shows the
moment that a breakpoint is hit. The breakpoints are listed in the lower left window with the
application output to the right.

148 User Guide

 Eclipse configuration management

Eclipse configuration management

The Rational Rhapsody Eclipse plug-in integrates a Rational Rhapsody model into the Eclipse
environment, enabling software developers to streamline their workflow with the benefit of
working within the same development environment. You can work in the code or model in a single
development environment. This enables you to use the Rational Rhapsody modeling capabilities
or to modify the code using the Eclipse editor, while maintaining synchronization between both
and easily navigating from one to the other.

Parallel development
When many developers are working in distributed teams, they often need to work in parallel.
These teams use a configuration management (CM) tool, such as Rational ClearCase, to archive
project units. However, not all files might be checked into CM during development.

Developers in the team need to see the differences between an archived version of a unit and
another version of the same unit that might need to be merged. To accomplish these tasks, they
need to see the graphical differences between the two versions, as well as the differences in the
code.

A Rational Rhapsody unit is any project or portion of a project that can be saved as a separate file.
These are examples of Rational Rhapsody units with the file extensions for the unit types:

Class (.cls)
Package (.sbs)
Component (.cmp)
Project (.rpy)
Any Rational Rhapsody diagram

Note
The illustrations in this section show the use of the Rational ClearCase Eclipse Team
plug-in. Different Team plug-ins (for example, Rational Synergy) might have different
graphical user interfaces and menus.

Rational Rhapsody 149

Eclipse platform integration

Configuration management and Rational Rhapsody unit view

For the Eclipse plug-in, your individual Team plug-ins handle configuration management
operations.

The Rational Rhapsody Unit View provides a hierarchical view of Rational Rhapsody model
resources as per the model structure. Use this view to perform configuration management
operations.

Navigating to the unit view

To navigate to the Unit View, on the model browser, right-click an element and select
Configuration Management > Select in Unit View.

From the model browser, you can choose Select with Descendants in Unit View. This menu
command selects all the descendants for Unit View.

Navigating to the model browser

To navigate to the model browser from the Unit View, right-click an element and select Show in
Model Browser.

The following figure shows the result of selecting Show in Model Browser.

150 User Guide

 Eclipse configuration management

Sharing a Rational Rhapsody model

Team members can share a Rational Rhapsody model using configuration management.

To share a Rational Rhapsody model using configuration management:

1. If you have multiple Rational Rhapsody models loaded, make whichever project you want
to share be the active one.
2. For the active Rational Rhapsody project, at the top-level project node in the Unit View,
choose Team > Share Project.

3. On the Share Project window, select the repository plug-in that you want to use to share
the selected project and click Next.

4. On the next window (which shows the name of the configuration management tool you
selected in the previous step), enter the required information. For example, if you are
using Rational ClearCase, specify a Rational ClearCase VOB for your project.

5. Click Finish.

6. Address any other windows that might open. For example, for Rational ClearCase, decide
which elements you want to add to source control by clearing or selecting the applicable
check boxes.

7. Click OK.

Rational Rhapsody 151

Eclipse platform integration

8. Restart Eclipse.

Performing team operations

To perform team operations in configuration management:

1. Before performing Team operations (such as Check In), save your Rational Rhapsody
model in the model browser.
2. For a Rational Rhapsody project in Unit View, right-click the element you want, choose
Team > (configuration management operation); for example, Team > Check Out.

3. On the window that opens, confirm the elements that you want to perform the
configuration management operation by clearing or selecting the applicable check boxes,
and then click OK.

Notice the white check mark within a green background that denotes an element that
is checked out.

Note
You can set Team plug-in related preferences through the Eclipse Preferences window
(choose Windows > Preferences).

152 User Guide

 Generate Rational Rhapsody reports

Rational Rhapsody DiffMerge facility in Eclipse

The DiffMerge tool can be operated inside and/or outside your CM software to access the units in
the repository. It can compare two units or two units with a base (original) unit. The units being
compared only need to be stored as separate files in directories and accessible from the PC running
the DiffMerge tool.

In addition to the comparison and merge functions, this tool provides these capabilities:

Graphical comparison of any type of Rational Rhapsody diagram

Consecutive walk-through of all of the differences in the units
Generate a Difference Report for a selected element including graphical elements
Print diagrams, a Difference Report, Merge Activity Log, and a Merge Report

Generate Rational Rhapsody reports

To generate reports from the model, use the Rational Rhapsody ReporterPLUS documentation tool
to create Microsoft Word, Microsoft PowerPoint, HTML, RTF, and text documents. The
ReporterPLUS pre-defined templates extract text and diagrams from a model, arrange the text and
diagrams in a document, and format the document.

Generating a report
To generate a report from the Rational Rhapsody model:

1. Choose Tools > ReporterPLUS > Report on all model elements or Report on selected
package.

2. On the ReporterPLUS Wizard: Select Task window, select the output format you want and
click Next.

3. Use the Browse button on the ReporterPLUS Wizard: Select Template window to
select a template from the template directory (for example, <Rational Rhapsody
installation path>\reporterplus\Templates) and click Next.

4. On the Confirmation window, review the report criteria, and then click Finish to produce
the report.

5. On the Generate Document window:

Enter a document name.

Browse to where you want to locate the files that will be produced.
Click the Generate button to generate your document.

Rational Rhapsody 153

Eclipse platform integration

6. Wait while your document is generated. ReporterPLUS spends some time loading the
template and the model. Then it analyzes the model and the model element relationships.

7. When available, click Yes to open your report.

154 User Guide

 Properties

As an open tool, Rational Rhapsody provides a high degree of flexibility in how you set up the
visual programming environment (VPE). Project properties are name-value pairs that enable you
to customize many aspects of environment interaction and code generation. You can set existing
properties, or create whole sets of new ones, to tailor Rational Rhapsody to your particular needs.

Note
This section contains generic information about the Rational Rhapsody properties and how
to work with them.

Rational Rhapsody properties overview

Properties are user-defined, tagged values that can be attached to any modeling element. You can
think of each element as having its own set of properties. Rational Rhapsody tools, such as the
code generator, reference many properties. You can modify properties to customize the tool to
work in a certain way, such as setting the default color of a state box in a statechart. You can
change properties at the site, diagram, package, configuration, or class level (or even at the
individual operation or attribute level). Only properties that are relevant for a particular element
are accessible from that element. The element on which you set a property determines its
effectiveness. In other words, setting a property for a configuration provides a default for elements
in the configuration. Precedence goes to the element with the lowest level of granularity. Meaning,
properties explicitly defined for an individual operation would override those set at the project
level.

Rational Rhapsody 155

Properties

Property groups and definitions

The Rational Rhapsody properties are classified according to subject and metaclass with the
individual property names listed under each metaclass. Selecting a subject, metaclass, or property
name listed in the Features window displays the definition of the selected item:

The right column indicates the type of information in the property value. Metaclasses are listed in
alphabetical order under each subject. For information on changing property values, see Rational
Rhapsody properties.

156 User Guide

 Rational Rhapsody properties overview

Subjects
The following table lists the Rational Rhapsody subjects.

Subject Description
Activity_diagram Controls the appearance of activity diagrams.
Animation Controls the behavior of black box animation.
ATL Controls ATL classes.
This subject applies only to Rational Rhapsody in C++.
Browser Controls the information displayed in the Rational Rhapsody
browser.
CG Controls how code is generated. These properties are
language-independent.
Collaboration_Diagram Controls the appearance of collaboration diagrams
COM Controls how mixed, distributed applications and objects find
and interact with each other over a network.
This subject applies only to Rational Rhapsody in C++.
ComponentDiagram Controls the appearance of component diagrams.
ConfigurationManagement Defines the command strings needed by various configuration
management (CM) tools to interface with Rational Rhapsody.
<ContainerTypes> Controls how items stored in containers are accessed and
manipulated.
The subject names are Java(1.1)Containers,
Java(1.2)Containers, OMContainers,
OMCorba2CorbaContainers, OMCpp2CorbaContainers,
OMCppOfCorbaContainers, OMUContainers,
RiCContainers, or STLContainers, depending on your
programming language and environment.
CORBA Controls how CORBA interacts with Rational Rhapsody.
This subject applies only to Rational Rhapsody in C++.
DeploymentDiagram Controls the appearance of deployment diagrams.
DiagramPrintSettings Controls how diagrams are printed.
Dialog Controls which properties are displayed on the Properties tab
General Controls the general aspects of the Rational Rhapsody display.
IntelliVisor Controls the IntelliVisor feature.
<lang>_CG Controls the language-specific aspects of code generation.
The subject name is C_CG, CPP_CG, or JAVA_CG.
<lang>_ReverseEngineering Controls how Rational Rhapsody imports legacy code.
The subject name is C_ReverseEngineering,
CPP_ReverseEngineering, or
JAVA_ReverseEngineering.

Rational Rhapsody 157

Properties

Subject Description
<lang>_Roundtrip Controls how changes made to the model are roundtripped to
the code, and vice versa.
The subject name is C_Roundtrip, CPP_Roundtrip, or
JAVA_Roundtrip.
Model Controls prefixes added to attributes, variables, and arguments
to reflect their type.
ObjectModelGe Controls the appearance of object model diagrams (OMDs).
QoS Provides performance and timing information.
ReverseEngineering Controls how Rational Rhapsody deals with legacy code.
RoseInterface Controls how Rational Rhapsody imports models from Rational
Rose® 98 or 2000.
RTInterface Controls how Rational Rhapsody interacts with requirements
traceability tools.
SequenceDiagram Controls the appearance of sequence diagrams.
SPARK Enables you to control the generation of SPARK annotations
from Rational Rhapsody in Ada models so they can be
analyzed by the SPARK Examiner.
Statechart Controls the appearance of statecharts.
TestConductor Controls contains properties that affect the TestConductor™
tool.
UseCaseExtensions Controls extended UCDs.
UseCaseGe Controls the appearance of use case diagrams (UCDs).
WebComponents Controls whether Rational Rhapsody components can be
managed from the Web, and specifies the necessary
framework for code generation.

158 User Guide

 Rational Rhapsody properties overview

Metaclasses
Under each subject, Rational Rhapsody lists metaclasses. Metaclasses define properties for groups
of things, such as attributes, classes, and configurations.

For example, under the Statechart subject and the State metaclass, the color, line_width, and
name_color properties determine the default color and line width of state boxes and the text color
of state names. The notation is Subject::Metaclass::Property; for example,
Statechart::State::Color. Note that you can always change the properties of an element in a
statechart or diagram on-the-fly (project properties specify the default appearance).

Rational Rhapsody 159

Properties

Regular expressions
Many properties use regular expressions to define valid command strings. For example, the
ParseErrorMessage property uses the following regular expression for Microsoft® environments:
([^(]+)[(]([0-9]+)[)] [:] (error|warning|fatal error)
This expression defines the rules used to parse error messages on Microsoft systems. If you
redefine properties that require regular expressions, you must use the correct expression syntax.

Regular expression syntax

Regular expression syntax is defined1 as a “regular expression is zero or more branches, separated
by |. It matches anything that matches one of the branches. A branch is zero or more pieces,
concatenated. It matches a match for the first, followed by a match for the second, and so on.”

A piece is an atom possibly followed by *, +, or ?.

An atom followed by * matches a sequence of 0 or more matches of the atom.

For example, the atom .* matches zero or more instances of any character (a period
matches any character).
An atom followed by + matches a sequence of 1 or more matches of the atom.

For example, the atom .+ matches one or more instances of any character.
An atom followed by ? matches a match of the atom, or the null string.

For example, the atom .? matches a single character or the null string, such as at the end
of an input string.
An atom is a regular expression in parentheses (matching a match for the regular
expression), a range, or:
– . (matching any single character)
– ^ (matching the beginning of the input string)
– $ (matching the end of the input string)
– A \ followed by a single character (matching that character)
– A single character with no other significance (matching that character)
Consider the following regular expression:
([a-zA-Z_][a-zA-Z0-9_]*)

1.Copyright (c) 1986 by U. of Toronto. Written by Henry Spencer.

160 User Guide

 Regular expressions

This regular expression, enclosed in parentheses, matches a sequence of two ranges, any single
uppercase or lowercase letter, or underscore character; followed by zero or more uppercase or
lowercase letters, digits 0-9, or the underscore character.

Parsing regular expressions

Parts of the expression contained within parentheses are called tokens.

The regular expression for the ParseErrorMessage property is as follows:

([^(]+)[(]([0-9]+)[)] [:] (error|warning|fatal error)
It consists of the following parts:

([^(]+) This is the first token. The caret at the beginning of the set is a NOT operator that
matches any character except those in the set. This token tells the parser to ignore all
characters until the first occurrence of an open parenthesis.
[(] The parser should search for exactly one opening parenthesis.
([0-9]+) This is the second token It tells the parser to search for a sequence of one or
more digits in the range of 0 to 9.
[)] The parser should search for exactly one closing parenthesis.
[:] The parser should search for exactly one colon.
(error|warning|fatal error} This is the third token. It tells the parser to search for
one of the strings “error,” “warning,” or “fatal error.”
The ErrorMessageTokensFormat property works with ParseErrorMessage to determine how many
tokens can be contained in an error message, and the relative positions in the message string of
tokens that represent the file name and line number of the error, respectively. The second token in
the sample regular expression would most likely represent a line number, depending on how
ErrorMessageTokensFormat was defined.

Based on this regular expression, the parser would interpret the string “(3457):warning” as a
valid error message indicating a warning condition at line 3457 in the program.

Rational Rhapsody 161

Properties

Property file format

All the property (*.prp) files use an LL1 syntax for a simple, recursive descent parser. The parser
currently has no error recovery and effectively stops at the first error. Tokens enclosed within curly
braces {} are optional. Those enclosed within angle brackets <> are further decomposed according
to their own BNF (Backus Naur Form) descriptions.

The BNF for the *.prp files is as follows:

<file> ::= {"Subject" <subject>} "end"
For example, the factory.prp file begins with an optional list of subjects, each beginning with
the keyword “Subject,” and ends with the required keyword “end”:
Subject General
Subject Statechart
Subject ObjectModelGe
.
.
.
end

<subject> ::= <name> {"Metaclass" <metaclass>} "end"

As another example, the subject General begins with a name, followed by a list of metaclasses,
followed by the keyword “end”:
Subject General
Metaclass Graphics
Metaclass Model
end

<metaclass> ::= <name> {"Property" <property>} "end"

The file contains the following type declarations:

“Bool”
A string that indicates a type with two possible values, TRUE or FALSE.

<enum values> ::= <quoted string>

The enum values string is a comma-separated list of legal, enumerated values. A second quoted
string indicates the default. For example, the quoted string “on,off” contains enumerated values.

<value> ::= <quoted string>

A value. For example, a property value could be the quoted string “Arial 10 NoBold NoItalic”.

<quoted string> ::= <quote> <escaped chars> <quote>

A quoted string is a string that starts and ends with double-quotes and can contain newlines. A
backslash must precede any literal double-quote or backslash characters within the string. For
example, “FALSE” is a quoted string.

162 User Guide

 Rational Rhapsody keywords

Rational Rhapsody keywords

Many properties reference other properties, using the $ symbol. For example, the command string
for the ConfigurationManagement::ClearCase::AddMember property begins as follows:
"$OMROOT/etc/Executer.exe"
This substring references the predefined variable OMROOT, set in your rhapsody.ini file to the
location of the Share directory in the Rational Rhapsody installation. Expanded, this string
becomes:
"<install_dir>\Share/etc/Executer.exe"
For a description, see The Executer.

Keywords are used in the following areas:

Makefile generation
Standard operations
Relation implementation properties
Names of generated operations
Headers and footers
Configuration management

Predefined variables
The following table lists the predefined variables used in Rational Rhapsody.

Keywords Where Used Description

$archive ConfigurationManagement The file name (including the full path)
of the archive that you selected in the
Connect to Archive window. This can
be either a file or a directory.
$archiveddirectory ConfigurationManagement The directory part of $archive. If
$archive is a directory, $archive
and $archiveddirectory are the
same.
$arguments ATL The arguments of the operation.
$Arguments <lang>_CG The event or operation argument’s
description, used by the
DescriptionTemplate property.

Rational Rhapsody 163

Properties

Keywords Where Used Description

$attribute CG The object of an operation on
attributes.
The qualifier :c capitalizes the name
of the attribute.
$base <lang>_CG The name of the reactive object.
$CheckOut ConfigurationManagement The command executed to check
configuration items out of the archive
using the main Configuration Items
window.
$class ATL The name of the ATL class.
$ClassClean Makefiles The list of class files used in a build.
$cname CG, <Container Types>, The name of the container used to
<lang>_CG hold relations. Typical containers are
arrays, lists, stacks, heaps, and maps.
$coclass ATL The name of the coclass that exposes
the COM interface.
$CodeGeneratedDate CG, <lang>_CG The date of code generation. This
information is printed in the headers
and footers of generated files.
$component ATL The name of the component,
$ComponentName CG The name of the component that
caused the code to be generated.
This information is printed in the
headers and footers of generated
files.
$ConfigurationName CG, <lang>_CG The name of the configuration that
caused the generation of the model
element found in a file. This
information is printed in headers and
footers of generated files.
$datamem ATL The data member.
$DeclarationModifier ATL The declaration modifier.
$Description <lang>_CG The element description, used by the
DescriptionTemplate property.
$Direction <lang>_CG The argument direction (in, out, and
so on), used by the
DescriptionTemplate property.
$dupinterface ATL The name of the duplicate interface.
$executable <lang>_CG The path to the executable binary file
generated by the Rational Rhapsody
code generator.

164 User Guide

 Rational Rhapsody keywords

Keywords Where Used Description

$FILENAME CPP_CG The name of the file used:
• To generate source code for
individual classes to user-
specified directories
• To specify that a statement should
not be imported during reverse
engineering (the #ifndef that
protects h files from multiple
includes)
$Fork Framework: start method Used to specify whether the
OMMainThread singleton event loop
should run on the application main
thread or in a separate thread.
$FullCodeGeneratedFileName CG, <lang>_CG The full path name of the file. This
information is printed in headers and
footers of generated files.
$FULLFILENAME CG The full name of the file used:
• To generate source code for
individual classes to user-
specified directories
• To specify that a statement should
not be imported during reverse
engineering (the #ifndef that
protects h files from multiple
includes)
$FullModelElementName CG, <lang>_CG The full name of a model element in
<package>::<class> format. is
printed in headers and footers of
generated files. For example,
Radar::Engine, for a class named
Engine found in a package named
Radar.
$FullName <lang>_CG The full path of the element
(P1::P2::C.a) used by the
DescriptionTemplate property.
$id ATL The identifier.
$IDInterface ATL The interface ID of a COM interface.
$index <Container Types> An index used to randomly access
items in a container.
$instance Property: Refers to the default initial instance of
CORBA::TAO::InitialInstance the TAO ORB.
$interface ATL The name of the interface.
$interfaceSeq Property: Represents the name of the CORBA
CORBA::Class::IDLSequence interface with the string Seq added to
the end of the term.

Rational Rhapsody 165

Properties

Keywords Where Used Description

$item CG, <Container Types> A class or instance whose behaviors
are implemented by a container.
Rational Rhapsody generates various
add, remove, find, and get
operations to manipulate items in
containers.
$iterator <Container Types> The name of the iterator used to
traverse a container.
$keyname <Container Types> The name of a key used to access
items in maps. A key is usually a
string that maps to a dictionary that is
used to locate items.
$label ConfigurationManagement An optional revision label of a
configuration item, provided in the
Check In/Check Out window.
$log ConfigurationManagement An optional comment provided in the
Check In window.
$LogPart ConfigurationManagement The user-specified comment for the
CM operation.
$Login CG, <lang>_CG The login name of the user who
generated the file. This information is
printed in headers and footers of
generated files.
$makefile <lang>_CG The name of the makefile generated
by the Rational Rhapsody code
generator.
$maketarget <lang>_CG Depending on the option selected in
the Code menu, this expands to one
of the following operations:
• Build
• Clean
• Rebuild
$member <lang>_CG The name of the reactive member
(equivalent to the base class) of the
object.
$mePtr <lang>_CG The name of the user object (the
value of the Me property). The
member and mePtr objects are not
equivalent if the user object is active.
$mode ConfigurationManagement A flag indicating the locking mode
provided in the Check In/Check Out
window. If the item is locked, $mode is
replaced with the contents of the CM
property ReadWrite. If unlocked,
$mode is replaced with the contents
of the ReadOnly property.

166 User Guide

 Rational Rhapsody keywords

Keywords Where Used Description

$ModePart ConfigurationManagement The locking mode of the CM
operation.
For example, you can check out a file
from an archive as either locked or
unlocked.
$Name <lang>_CG The element name, used by the
DescriptionTemplate property.
$noOfArgs ATL The number of arguments for the
operation.
$OMAdditionalObjs Makefiles The list of files to be included in the
executable.
$OMAllDependencyRule Makefiles The dependency rule of a specific
source file (A.cpp: A.h B.h
C.idl).
$OMBuildSet Makefiles The compiler switches for Debug
versus Release mode, as specified in
the Settings window for the active
configuration.
$OMCleanOBJS Makefiles The list of delete commands for each
object file in the makefile. Each entry
in the list is created from the value of
the ObjCleanCommand property.
$OMCOM Makefiles Specifies that the COM application to
be linked is a windows application
rather than a console application. This
keyword is resolved based on the
value of the <lang>_CG::
<Environment>::COM property.
$OMConfigurationCPPCompile Makefiles The compiler switches specified by
Switches the CompileSwitches property for a
configuration.
$OMConfigurationLink Makefiles The link switches of the configuration,
Switches set in the Settings tab for the
configuration.
$OMContextDependencies Makefiles The list of dependencies and the
compilation command for each model
file that should be built as part of the
component. Each entry is made up of
the value of the DependencyRule
property followed by the value of the
CPPCompileCommand property.

Rational Rhapsody 167

Properties

Keywords Where Used Description

$OMContextMacros Makefiles The set of generated macros,
including:
• OMROOT
• CPP_EXT/C_EXT
• H_EXT
• OBJ_EXT
• LIB_EXT
• INSTRUMENTATION
• TIME_MODEL
• TARGET_TYPE
• TARGET_NAME
• The “all” rule
• TARGET_MAIN
• LIBS
• INCLUDE_PATH
• ADDITIONAL_OBJS
• OBJS
For more information, see
MakeFileContent.
$OMCPPCompileCommandSet Makefiles The compilation switches related to
the CPPCompileDebug/
CPPCompileRelease properties.
The property to be used is based on
the value of the BuildCommandSet
property. Set the value of
BuildCommandSet using the
configuration Settings tab in the
browser.
$OMCPPCompileDebug Makefiles The compile switches needed to
create a Debug version of a
component in a given environment, as
specified by the CPPCompileDebug
property.
$OMCPPCompileRelease Makefiles The compile switches needed to
create a Release version of a
component in a given environment, as
specified by the
CPPCompileRelease property.

168 User Guide

 Rational Rhapsody keywords

Keywords Where Used Description

$OMFileCPPCompileSwitches Makefiles This is used in the
CPPCompileCommand property to
bring in additional GUI-defined
settings. The content is generated by
Rational Rhapsody (either based on
content of fields or based on internal
rules).
It is one of the predefined keywords
including, but not limited to:
• $OMCPPCompileDebug
• $OMCPPCompileRelease
• $OMLinkDebug
• $OMLinkRelease
• $OMBuildSet
• $OMContextMacros
$OMDefaultSpecification Makefiles Supports the default specification/
Directory implementation source directory
feature.
To set a default directory for a
configuration, set the <lang>_CG::
Configuration::
DefaultSpecification-
Directory and <lang>_CG::
Configuration::
DefaultImplementation-
Directory properties
$OMDEFExtension Makefiles The extension of the definition file
(.def). This keyword applies to the
MicrosoftDLL/COM environments.
$OMDllExtension Makefiles The extension of the dynamic linked
library file (.dll). This keyword
applies to the MicrosoftDLL/COM
environments.
$OMExeExt Makefiles The extension of the compiled
executable.
$OMFileDependencies Makefiles Used as part of a source file
dependency line. It is a calculated list
of files on which the source file
depends.
$OMFileImpPath Makefiles The relative name and path of the
implementation file. It is used in a
source file dependency and
compilation commands.

Rational Rhapsody 169

Properties

Keywords Where Used Description

$OMFileObjPath Makefiles The relative path and name of an
object file that is related to a given
implementation and specification files.
It is used as part of a file compilation
command.
$OMFileSpecPath Makefiles The relative path and name of a
specification file. It is used in a source
file dependency line.
$OMFlagsFile Makefiles Maintained for backwards
compatibility.
$OMImpIncludeInElements Makefiles The list of all #includes done in the
related implementation file. It is used
as part of a source file dependency
line.
$OMImplExt Makefiles The extension of an implementation
file generated for a model element.
$OMIncludePath Makefiles The include path. The path is
calculated from dependencies
between components and from the
Include Path setting in the active
component/configuration feature
window.
$OMInstrumentation Makefiles The active configuration
instrumentation mode (None, Tracing,
or Animation).
$OMInstrumentationFlags Makefiles Represents the preprocessor
directives required for the selected
type of instrumentation: animation,
tracing, or none.
$OMInstrumentationLibs Makefiles Represents the libraries required for
the selected type of instrumentation:
animation, tracing, or none.
$OMLibExt Makefiles The extension of library files.
$OMLibs Makefiles The names of additional libraries
(besides the framework library) to link
when building a component. It is
calculated from dependencies
between components and the
Libraries list in the active component/
configuration feature windows.
$OMLibSuffix Code Generation Represents the suffix to use for library
names. The keyword is replaced by
the value of the DebugLibSuffix
property or the ReleaseLibSuffix
property depending upon the build.

170 User Guide

 Rational Rhapsody keywords

Keywords Where Used Description

$OMLinkCommandSet Makefiles The link switches related to the
LinkDebug/LinkRelease
properties. The property to be used is
based on the value of the
BuildCommandSet property. Set the
value of BuildCommandSet using
the configuration Settings tab in the
browser.
$OMLinkDebug Makefiles The environment-specific link
switches used to build a Debug
version of a component. This is the
value of the LinkDebug property.
$OMLinkRelease Makefiles The value of the LinkRelease
property.
$OMMainImplementationFile Makefiles The main file name and path:
[<imp dir>/]$TARGET_
MAIN)$(CPP_EXT)
$OMMakefileName Makefiles The name of the makefile.
$OMModelLibs Makefiles The library component the model
depends on.
For example, if executable
component A depends on the library
component L, this keyword is
replaced with the string
<filepath>\L.lib.
$OMObjExt Makefiles The extension of object files
(temporary compiler files) for a given
environment. This is the value of the
ObjExtension property.
$OMObjs Makefiles The list of object files to link into the
build by the makefile.
$OMObjectsDir Makefiles A calculated keyword based on the
property <lang>_CG::
<Environment>::
ObjectsDirectory).
$OMROOT ConfigurationManagement, The location of the \Share
General, <lang>_CG, subdirectory in the Rational Rhapsody
<lang>_Roundtrip, makefiles installation. This is set in your
rhapsody.ini file.
$OMRPFrameWorkDll Makefiles Links the COM application with the
DLL version of the framework instead
of the default static libraries. This
keyword is resolved based on the
value of the <lang>_CG::
<Environment>::
RPFrameWorkDll property.

Rational Rhapsody 171

Properties

Keywords Where Used Description

$OMRulesFile Maintained for backwards
compatibility.
$OMSourceFileList Makefiles (Rational Rhapsody in J) Lists the
source (*.java) files used in a build.
$OMSpecExt Makefiles The extension of the specification file
generated for a model element.
$OMSpecIncludeInElements Makefiles Lists all the #includes done in the
related specification file.
$OMSubSystem Makefiles The type of program for the Microsoft
linker (for example, windows).
$OMTargetMain Makefiles The name of the file that contains the
main() function for an executable
component.
$OMTargetName Makefiles The name of the compiled version of
a component.
$OMTargetType Makefiles The type of component to be built
(library or executable),
$OMTimeModel Makefiles The time model setting for a
configuration (simulated or real time).
$OMUserIncludePath INTEGRITY build files (.gpj) Represents the content of the Include
Path field found on the Settings tab of
the Features window for
configurations. This content is
included in generated .gpj files for
environments that use such files, for
example, INTEGRITY5.
$operations ATL The list of operations.
$opname ATL The name of the operation.
$opRetType ATL The return type of the operation.
$package ATL The name of the package.
$PackageLib ATL The package library.
$ProgID ATL The value of the ProgID property
(Default = $component.$class.1).
$projectname ConfigurationManagement The project name.
$<Property> <lang>_CG The value of the element property
with the specified name (under C or
CPP_CG::CG::
<metatype>). This keyword is used
by the DescriptionTemplate
property.

172 User Guide

 Rational Rhapsody keywords

Keywords Where Used Description

$RegTlb ATL Specifies whether the COM server
needs to register its type library.
Automatically expands to TRUE/
FALSE depending upon COM ATL
server includes type library.
$RhapsodyVersion CG, <lang>_CG The current version of Rational
Rhapsody, not including the build
number. This information is printed in
headers and footers of generated
files.
$rhpdirectory ConfigurationManagement The path to the _rpy directory, which
consists of the project repository. The
repository contains all the
configuration items for a project.
$Signature <lang>_CG The operation signature, used by the
DescriptionTemplate property.
$state Properties In the code generated by Rational
CPP_CG::Framework::IsInCall Rhapsody for checking whether an
CPP_CG::Framework::IsComple application is in a given state, this
tedCall keyword is replaced by the state
name.
$target <Container Types>, <lang>_CG The target of an operation on
relations. This is generally the role
name.
For example, in a class with a relation
called myServer, the role name
myServer would replace the variable
$target when expanding properties
that involve that relation. The value
add$target:c would become:
addMyServer()
The qualifier :c capitalizes the role
name.
$Target <lang>_CG The other end of the association,
used by the DescriptionTemplate
property.
$targetDir ConfigurationManagement The target directory.
$ThreadModel ATL The value of the ThreadingModel
property (Default = Apartment).
$tlbPath ATL The full path of the COM type library
file.

Rational Rhapsody 173

Properties

Keywords Where Used Description

$type CG, <lang>_CG The name of the type.
For example, if you create a type
named MyType and set its in
property to "const $type&", the
generation of an in argument will be
as follows:
"const MyType& <argname>"
$Type <lang>_CG The argument type, used by the
DescriptionTemplate property.
$TypeName ATL The value of the TypeName property,
which specifies the declaration of the
class type being registered (Default =
$class).
$unit ConfigurationManagement Unit of collaboration. This is the name
of the file that corresponds to the
configuration item (package,
configuration, or diagram) on which a
CM command operates. If more than
one unit is provided, the command is
performed repeatedly in a for each
loop.
$VersionIndepProgID ATL Replaced with the value of the
VersionIndepProgID property
(Default = $component.$class).
$VtblName <lang>_CG The name of the object's virtual
function table, specified by the
ReactiveVtblName property.

The following table lists the predefined Rational Rhapsody macros used in the framework files and
makefiles.

Macro Description
AR The command to build a library.
ARFLAGS The flags used to build a library.
CP Environment-specific copy command.
CPP_EXT Environment-specific extension for C++ implementation files (for example,
.cpp).
DLL_CMD Expands to the DLL link command that initiates the DLL link phase of a
build
DLL_FLAGS Expands to the switches applied to the DLL link command
H_EXT Environment-specific extension for C++ implementation files (for example,
.h).

174 User Guide

 Rational Rhapsody keywords

Macro Description
INCLUDE_QUALIFIER The qualifier used in a given environment to designate an include file in the
compiler or link switches.
LIB_CMD The command to build a library.
LIB_EXT Environment-specific extension for library files (for example, .lib).
LIB_FLAGS The flags used to build a library.
LIB_NAME The name of a library.
LIB_POSTFIX The postfix added between the main file name and the extension. The
possible values are as follows:
• sim for simulated time (for example, oxfsim.lib)
• inst for instrumentation (for example, oxfinst.lib)
• siminst for simulated time and instrumentation (for example,
oxfsiminst.lib)
This macro is not used for DLLs.
LIB_PREFIX The prefix added to the beginning of a file name. For example, the prefix
“Vx” is added to VxWorks libraries.
This macro is not used for DLLs.
LINK_CMD Expands to the link command that initiates the link phase of a build
LINK_FLAGS Expands to the link switches applied to the link command
OBJ_EXT The environment-specific extension for object files (for example, .o or
.obj).
OBJS The intermediate object files to be built (for example, aombrk.obj).
PDB_EXT The environment-specific extension for PDB debug files (for example,
.pdb).
RM The environment-specific remove command for deleting files.
RMDIR The environment-specific remove command for deleting directories. This is
used in the clean rules when you set the
<lang>_CG::<Environment>::ObjectsDirectory property.

Rational Rhapsody 175

Properties

Map custom properties to keywords

You can define custom keywords in makefile template properties and standard operations. The
property name for the custom keyword should be the same as the keyword string. For example, for
the keyword $AAA, the property name should be AAA.

Define the property in a specific Subject and Metaclass, as follows:

Property Type Subject Metaclass

Makefile CG/<lang>_CG Component/
Configuration/
<Environment>
Standard operations CG/<lang>_CG The keyword context
(class, relation, attribute,
and so on)

176 User Guide

 Rational Rhapsody properties

Rational Rhapsody properties

Properties affect aspects of your model, such as the appearance of graphics in various graphic
editors, how code is generated, or configuration management settings.

Using the Properties tab in the Features window

Rational Rhapsody provides easy access to the properties through the interface. Use either of the
following methods to display properties:

With a project open, choose File > Project Properties to access all the properties for a
model. The Features window displays with the Properties tab already selected.
Right-click an item in the browser or on a diagram and select Features to open the
Features window, and then select the Properties tab to list the properties for the selected
item.

Rational Rhapsody 177

Properties

Properties definitions display

The Properties tab uses a tree structure to display the subjects, metaclasses, and properties.

In the left column, the subjects are listed in boldface font; expand the plus sign to view the
metaclasses for a particular subject. When you expand a metaclass, the corresponding properties
are listed in the left column, with their current values (if any) listed in the right column.

For example, in the figure, the ObjectModelGe::Class::ShowName property can have the values
Full_path, Relative (the default value), and Name_only.

Note that items are usually in alphabetical order; however, metaclasses that are of the same type as
the context are “pushed up” to be first. For example, if you are viewing the properties of a selected
class, the first metaclass displayed is CG::Class.

Selecting a property displays the definition for the property in the bottom pane of the window.
Each time a new property is selected, its definition displays below. Definitions are displayed for all
three of the property levels: subject, metaclass, and the individual property.

Searching for properties

The Properties tab contains a menu to filter the properties displayed in the window.

The All option displays all of the available properties for your selection. You can display only the
Overridden properties for the model or only the properties you overrode locally with the Locally
Overridden option. The Common properties are those most often changed for the selected type of
item.

The Filter menu option lets you search for specific properties by entering a filter string. Rational
Rhapsody displays only the properties that contain the text you entered. When you are filtering the
properties and select the Match property description check box, Rational Rhapsody searches the
property definitions for the string you entered, as well as the property name.

Note
The Filter mechanism is not case-sensitive and does not allow the use of wildcards or
expressions.
If you enter more than one word as the Filter, Rational Rhapsody performs an “or” search and
displays all of the properties that contain any one of the words entered. To limit the search to only
the definitions containing the entire phrase, enclose the words in the search string within quotation
marks.

As long as the Features window (or standalone properties window) remains open, the selection
you made from the menu (filter text and check box setting) is retained. When the Features window
is closed, these are reset.

178 User Guide

 Rational Rhapsody properties

Resizing the Features window

Some of the properties might have long tables of information. You might find it necessary to resize
the Features window in order to see these tables without awkward text wrapping outside the table
columns. You can use the typical Windows methods to resize the Features window.

In addition, you can select the vertical line separator to resize the columns for the property names
and their values. When you click the vertical separator, a solid-looking line displays so you can
control the column widths and display. You can click the horizontal separator to resize the bottom
pane of the Properties tab where the property definitions appear.

Note
Any continuation of a long “Default Value” is indented under that heading until a new table
entry begins.

Rational Rhapsody 179

Properties

Filtering views
To select the types of properties that are displayed in the Features window, you can specify the
view for the View menu.

The possible views are as follows:

All displays all the available properties, according to context.

Overridden displays only those properties whose default values have been overridden, up
to the project level. When you select this view, the GUI displays all the overridden
properties from the selected element up to the scope of the project; overridden properties
at a scope higher than the selected element are displayed as regular, non-overridden
properties. From the menu, you can also select the Un-override option to reverse this
action.
Locally Overridden displays only the locally overridden properties for the selected
element. A selected element is a project, component, configuration, package, diagram,
view element, and any other model element displayed in the browser.
Note: To specify the default filter used, set the
Dialog::General::PropertiesDialogDefaultFilter property.
Common displays the properties contained in the
Dialog::<Metaclass>::CommonProperties property. This is the default view.
Filter displays the Filter Properties window to search for specific properties and
definitions.

180 User Guide

 Rational Rhapsody properties

Filtering properties
To search for specific property names or text in descriptions, select Filter from the Properties tab
View menu. This feature allows you to input and search for any text in the Property names and the
descriptions. Selecting the “Match property description” check box searches property descriptions
in addition to the names. Text located through a Filter Properties search is displayed in bold type in
the property definition area of the Features window.

Rational Rhapsody 181

Properties

Adding and removing the common view

The common view enables you to see only a subset of the hundreds of Rational Rhapsody
properties that are available. This makes the properties GUI much easier to use. You can easily add
properties that you use frequently to the common view, or remove properties that you do not use.

To add a property to the common view:

1. In the properties GUI, select the All filter so you can find the property to add to the
common view.

2. Right-click the property you want to add to the common view and select Add To common
list.
To remove a property to the common view:

1. In the properties GUI, select the Common filter so you can find the property to add to the
common view.

2. Right-click the property you want to remove and select Remove from common list.

Property controls
The Property tab uses different controls depending on the value type of the property (enum,
Boolean, and so on). The following table lists the property types and the corresponding controls.

Type Control
Boolean Check box (a check mark = checked)
Color Color selection box, with samples and their RGB
equivalents
Enum Drop-down list
MultiLine Multiline edit control
Numeric value Edit box
Text string Text editing box

182 User Guide

 Rational Rhapsody properties

Overridden properties
When you override the default value of a property, the property name is displayed in purple. The
following figure shows an overridden property.

Removing an override
To remove an override:

1. Right-click the property value to display the Un-override command.

2. Click Un-override. The property is reset to the default value.

3. Click OK.

Rational Rhapsody 183

Properties

The following figure shows the Un-override command.

184 User Guide

 Rational Rhapsody properties

Changing a property value

To change the value of a property using the Features window:

1. Choose File > Project Properties to set properties at the project level.

or

To set properties at the component level, right-click the component whose property you
want to change, choose Features > Properties, and then select the Properties tab.

2. If wanted, select a different group of properties using the View drop-down list.

3. Locate the appropriate property under the subject and metaclass.

For example, to change the class code editor for your model, expand the General node in
the list of subjects, then expand the Model metaclass to locate the ClassCodeEditor
property.

4. Select the new value for the property in the right-hand column (for example, to change the
value of the ClassCodeEditor property from Internal to CommandLine).

The overridden property is displayed in purple.

5. Click OK.

Rational Rhapsody 185

Properties

Visibility of properties
In general, a subject is displayed for an element if it contains a metaclass that matches the
metaclass of the element. The following table lists the exceptions to this rule.

Subjects Visible Under Only the

Subjects Visible Only Subjects Visible Under
Configuration/Component and the
Under the Project Diagrams and the Project
Project
• General • Diagrams • ConfigurationManagement
• RTInterface • Statechart • ReverseEngineering
• RoseInterface • ObjectModelGe • CPP_ReverseEngineering
• Browse • SequenceDiagram
• Report • UseCaseGe
• IntelliVisor • ComponentDiagram
• DeploymentDiagram
• Collaboration_Diagram
• Activity_diagram

186 User Guide

 Rational Rhapsody properties

PRP files
Default properties are assigned in the factory and site default files, factory.prp and site.prp,
respectively. These files are located in the $OMROOT\Share\Properties directory and provide a
way to tune project properties on an individual or site-wide basis without recompiling Rational
Rhapsody.

Do not change the factory.prp file to make individual site requirements. Instead, change the
site.prp file for an individual site. Settings in the site.prp file will override the settings in the
factory.prp file. In this way, you can always return to factory default settings in case of mistakes.

Customizing existing properties

You can customize the existing Rational Rhapsody subjects, metaclasses, and/or properties or
create new ones. There are many reasons for creating or modifying subjects, metaclasses and/or
properties. For example, you might be using an unsupported OS, compiler (configuration), and/or
configuration management tool.

When creating a new subject, you can keep existing metaclasses and properties intact. For
example, the subjects OMUContainers, OMContainers, and STLContainers are all different
subjects which contain the same metaclasses and properties.

Likewise, when creating a new metaclass, you can keep existing subjects and properties intact.
You can also create new properties under existing subjects and metaclasses. For example, if you
were using a testing tool that Rational Rhapsody did not support, you might create new properties
under an existing metaclass.

You can create new metaclasses and properties using existing Rational Rhapsody properties. For
example, to add a new configuration management tool to Rational Rhapsody:

1. In the factory.prp file, locate the CM tool property.

2. To the comma-separated enum values string, add the name of the new CM tool.

3. If you want this tool to be the default CM tool, change the second quoted string from None
to the name of the new tool.

When you restart Rational Rhapsody, you will see the name of the new CM tool listed in
the drop-down list of the Modify window for the CM tool property.

4. Block and copy the section of code for an existing metaclass. Be sure to include the
closing “end” for the metaclass block.

5. Rename the new metaclass to the name you specified in Step 2.

Rational Rhapsody 187

Properties

6. Edit the value of every property in the new metaclass, depending on the requirements for
CM commands within the individual CM tool.

To do the final step, see the documentation for the CM tool to determine the syntax for
commands in that tool. Once you know what information the CM tool requires and the
syntax of commands in that tool, you can use regular expression syntax and Rational
Rhapsody-internal variables to create the appropriate command strings for the tool.

Note
Do not change the original settings in the factory.prp file because you would not be able
to roll back to the default settings.

188 User Guide

 Rational Rhapsody properties

Adding customized properties

You can add your own properties to existing metaclasses. You can add properties for special
annotations, specification numbers, part numbers, traceability information, and any kind of
comment. For example, you might require that each class be assigned a safety property and a serial
number.

To add a custom property:

1. Open the site.prp file in the Properties directory.

2. Under the appropriate subject and metaclass, add the new property. Make sure to put in the
correct number of end statements.

Adding comments to the properties files

Although Rational Rhapsody does not have a formal way to add comments to the property files,
you can add comments by creating your own properties.

To add comments to a properties file:

1. Create new subjects, for example:

Subject .PRP File

Subject SiteComment site.prp
Subject SiteCPPComment siteC++.prp
Subject SiteCComment siteC.prp

2. Create a new metaclass named Comments under each subject.

3. To each metaclass, add a new property of type String or MultiLine that contains the
comment text.

If you place this information on top of your site<Lang>.prp, you benefit in the following ways:

You can add comments in the file header to document why you made changes.
Access from inside Rational Rhapsody via the Property tab to get an overview of the
version and changes inside your site properties files. However, you must keep the
comments and content in sync manually.
Gain the ability to bring site settings into the Reporter documentation.

Note
Do not use the String comment ("") inside the assigned strings of the comment properties.

Rational Rhapsody 189

Properties

Example
The following example shows a portion of the SiteC++.prp file with comment properties.
Subject SiteCPPComment
Metaclass Comments
Property RhpVersion String "v7.5 SiteC++ for Rhapsody
Build 1368921"
Property ChangeAuthor String "John Smith, Acme Co."
Property LastChange String "01.30.2009"
Property ChangeHistory MultiLine "Version 1.0
02.08.2009"
Property ChangeList MultiLine "
List of Changed Properties
Optimization Properties:
* CPP_CG->Attribute->AccessorGenerate to False
* CPP_CG->Attribute->MutatorGenerate to False
* CPP_CG->Relation->RemoveKeyGenerate to False
* CPP_CG->Relation->RemoveKeyHelpersGenerate to
False
Other properties:
* None
"
Property GeneralComment MultiLine "
Purpose of the changes in siteC++.prp:
I like challenges!
Any questions?
"
end
end
end

190 User Guide

 Rational Rhapsody properties

Including PRP files

To include one .prp file in another, use the Include directive. Rational Rhapsody will replace the
directive with the contents of the specified file.

The syntax of the directive is as follows:

Include "path"
The specified path can be relative to the file that does the include, and should include the .prp
extension. In addition, the path can include an environment variable. For example:
Include "$MY_PATH\some_dir\my_file.prp"
To include more than one .prp file, simply use multiple directives. For example:
Include "$MY_DIR\my_file1.prp"
Include "$MY_DIR\my_file2.prp"
Note the following information:

Include statements must be outside of a Subject block, either before or after. Therefore,
Rational Rhapsody expects every included .prp file starts with a Subject line. If not,
Rational Rhapsody generates an error.
Rational Rhapsody does not check for loops. Therefore, a loop in the include files might
cause an infinite loop when the .prp file is read.
You can nest include statements. For example:
Include "C:\Rhapsody\Share\Properties\IndividualSite.prp"

Subject General
Metaclass Model
Property BackUps Enum "None,One,Two" "Two"
end
end
Include "..\Properties\IndividualSite.prp"

Subject General
Metaclass Model
Property AutoSaveInterval Int "11"
end
end
Include "IndividualSite.prp"

Rational Rhapsody 191

Properties

Property inheritance
The level at which you set a property can affect other elements. For example, if you set a property
for a dependency at the class level, and not on an individual dependency, it applies to all the
dependencies in that class.

The following illustration shows how property values are inherited.

Factory.prp Factory<lang>.prp Site<lang>.prp

Component profile project Site.prp

configuration package

operation
class
attribute

relation

Note
Note that if a stereotype is applied to an element, a property assigned to that stereotype takes
precedence over the element's inherited property values (locally overridden properties take
precedence over both inherited properties and those applied via a stereotype).

192 User Guide

 Concepts used in properties

Concepts used in properties

The following sections provide a brief overview of the concepts used in the Rational Rhapsody
properties.

Static architectures
Several properties in Rational Rhapsody provide support for static architectures, found in hard
real-time and safety-critical systems that do not use dynamic memory management during
runtime. When these properties are used, all events (including timeouts and triggered events) are
dynamically allocated during the initialization phase. Once allocated, the memory pool (or event
queue) remains static in size during the life of the application. It is important to note that dynamic
memory management capabilities are still required in order to initialize these systems. In its
current implementation, Rational Rhapsody does not generate applications that can be run in
environments that are completely without dynamic memory management capabilities.

Properties that provide support for static architectures include the following properties:

BaseNumberOfInstances

AdditionalNumberOfInstances

ProtectStaticMemoryPool

EmptyMemoryPoolCallback

EmptyMemoryPoolMessage

TimerMaxTimeouts

IncludeFiles
The IncludeFiles property (under the <ContainerTypes> metaclasses) enables the selective
framework includes of templates based on a particular relation implementation.

If this property is defined, includes of the files listed in the property are added to the specification
files for classes participating in a relation.

Include files can also be added to class implementation files if the container is added by reference.
If the Containment property is set to Reference, a forward declaration of the container is added to
the class specification file, and the #include is added to the class implementation file. A new set
of properties that describe the forward declaration of the container is added to each container
implementation metaclass, and the necessary modifications are made to the code generation.

Rational Rhapsody 193

Properties

Selective framework includes

Some compilers (for example, VxWorks) tend to instantiate redundant copies of templates that are
defined in the C++ framework. These redundant instantiations cause the resulting code
(executable) to be much larger.

To enable the use of relations without templates, a set of typeless (void*) containers is supplied as
an alternative implementation. The generated code for relations that use the typeless containers is
responsible for supplying a type-safe interface.

However, supplying typeless containers does not entirely solve the problem because templates are
still included via the framework .h files. To resolve this issue, selective includes of framework
objects must be used to avoid getting the template definitions “in the back door.”

To support selective framework includes, the oxf.h file has been minimized to include only the
most basic files. The following properties have also been added:

IncludeFiles

ActiveIncludeFiles

ReactiveIncludeFiles

ProtectedIncludeFiles

StaticMemoryIncludeFiles

Reactive classes
A class is considered reactive if it:

Has a statechart
Consumes events
Is a composite

Units of collaboration
In the property descriptions, the term “unit” refers to a unit of collaboration, which can be one of
the following types:

Object type or class

Package (*.sbs file)
Configuration (*.cfg file)
Object model diagram (*.omd file)
Sequence diagram (*.msc file)

194 User Guide

 Concepts used in properties

Use case diagram (*.ucd file)

Instances (objects), statecharts, and events are not exchanged in isolation, but together with
packages. Therefore, they are not considered units of collaboration.

The Executer
Several Rational Rhapsody properties include calls to the Executer to execute batch files. The
location of both the Executer and the target-specific batch makefile ($makefile) are given relative
to the $OMROOT environment variable.

The commands that reference the Executer do so for two reasons:

To allow definition of a single property to represent a series of commands. The Executer

executes each one by calling system().
To permit execution of commands by means closely resembling those of the shell’s
command-line (important for wildcards and escape characters).
The Executer accepts two string arguments:

An executable command, or list of commands separated by semicolons.

The directory from which to run the commands. If not specified, the commands are run
from the current directory. (For CM tools, the “current directory” is the _rpy directory).

Rational Rhapsody 195

Properties

Rational Rhapsody environment variables

In addition to the properties, numerous environment variables help define the Rational Rhapsody
environment. These environment variables are stored in the rhapsody.ini file, normally located
under C:\Winnt on Windows systems.

The following table lists the environment variables used by Rational Rhapsody. For ease of use,
the environment variables are listed by section in the order in which they occur in the file.

Environment Variable Description

General section
OMROOT = path Specifies the location of the Share subdirectory of the Rational
Rhapsody installation.
For example, if during the installation you specify D:\Rhapsody
for the destination folder, the value of OMROOT is as follows:
$OMROOT = D:\Rhapsody\Share
OMDOCROOT = path Specifies the root directory for some Rational Rhapsody
documentation as PDF files.
OMHELPROOT = path Specifies the root directory for the Rational Rhapsody online help.
RY_LICENSE_FILE Specifies licensing information needed by FLEXlm. This variable is
set to one of the following values:
• The path to the license.dat file
• 1717@hostname, where 1717 is the port number (any number
between 1024 and 65534) and hostname is the name of the
Rational Rhapsody license server machine
AnimationPortNumber=6423 Specifies the port number used for communicating with the
animation server.
UseVBA = Boolean Specifies whether VBA macros can be used.
For example:
UseVBA = CHECKED
EnableWebDownload = Boolean Enables or disables the Download from Web feature.
For example:
EnableWebDownload=CHECKED
DefaultEdition = edition Specifies the default edition of Rational Rhapsody to use.
For example:
DefaultEdition = Developer
DefaultLanguage = language Specifies the default programming language for Rational
Rhapsody.
For example:
DefaultLanguage = C++

196 User Guide

 Rational Rhapsody environment variables

Environment Variable Description

ImplementBaseClasses=CHECKED Controls whether the Implement Base Classes window is displayed
in implicit requests. By default, this window is displayed only when
you explicitly open it.
If you select the Automatically show this window check box on the
window, Rational Rhapsody writes this line to the rhapsody.ini
file. If wanted, you can add this line directly to the rhapsody.ini
file to automatically display the window.
RHAPSODY_AFFINITY = number Sets the affinity of the Rational Rhapsody process. This variable is
designed to address cases where Rational Rhapsody has
problems with more than one processor.
For example, to run Rational Rhapsody on a single processor, add
the following line to the rhapsody.ini file:
RHAPSODY_AFFINITY=1
A zero value or lack of this variable disables the mechanism.
NO_OUTPUT_WINDOW=CHECKED Disables the output window for reverse engineering (RE)
messages to increase performance. RE messages are logged in the
file ReverseEngineering.log.
Helpers section
name<#>= string Specifies the name of the helper.
For example:
name1=Reverse Engineer Ada Source Files
command<#> = path to .exe Specifies the invocation command for the helper.
For example:
command1=J:\Rhapsody5\
AdaRevEng\bin\AdaRevEng.exe
initialDir<#> = path Specifies the initial directory for the helper.
For example:
initialDir1=J:\Rhapsody5\
AdaRevEng
isVisible<#> = 0 or 1 Specifies whether the helper is visible in the Tools menu.
For example:
isVisible1=1
isMacro<#> = 0 or 1 Specifies whether the helper is a VBA macro.
For example:
isMacro1=0
arguments<#> = string Specifies the command-line arguments for the helper.
For example:
arguments1=
numberOfElements = number Specifies the number of helpers.
For example:
numberOfElements=1

Rational Rhapsody 197

Properties

Environment Variable Description

CodeGen section
ExternalGenerator = path Specifies the path to the external generator (if used).
For example:
ExternalGenerator=
J:\Rhapsody5\Sodius\
Launch_Sodius.bat
Note that this variable applies only to Rational Rhapsody in Ada.
ModelCodeAssociativityMode = Specifies the dynamic model-code associativity (DMCA) status. A
enum value of Dynamic means that changes to the model are
dynamically updated in the code, and vice versa.
For example:
ModelCodeAssociativityMode=
Dynamic
Tip section
TimeStamp = Specifies the date and time you ran the Rational Rhapsody
installation.
For example:
TimeStamp=Mon Apr 21
09:34:31 2003
FilePos = position Specifies the default position at which to display the Tip of the Day.
For example:
FilePos=3200
StartUp = Boolean Specifies whether to display the Tip of the Day when you start
Rational Rhapsody.
For example:
StartUp = 1
Animation section
ViewCallStack = 0 or 1 Specifies whether the call stack should be visible in the next
animation session.
For example:
ViewCallStack=0
ViewEventQueue = 0 or 1 Specifies whether the event queue should be visible in the next
animation session.
For example:
ViewEventQueue=0
Settings section
WindowPos = position Specifies the position of the Rational Rhapsody window on your
screen.
For example:
WindowPos=0,2,-32000,-32000,
-1,-1,25,38,926,669

198 User Guide

 Rational Rhapsody environment variables

Environment Variable Description

BarsLayout section
BrowserVisible = Boolean Specifies whether the browser should be visible, according to the
settings from the last session.
For example:
BrowserVisible=TRUE
FeaturesVisible = Boolean Specifies whether the Features window should be visible,
according to the settings from the last session.
For example:
FeaturesVisible=FALSE
FeaturesFloating = Boolean Specifies whether the Features window should be floating or
docked, according to the settings from the last session.
For example:
FeaturesFloating=TRUE
BrowserFloating = Boolean Specifies whether the browser should be floating or docked,
according to the settings from the last session.
For example:
BrowserFloating=FALSE
Bar<#> Groups the settings corresponding to each toolbar.

For example:
[BarsLayout-Bar29]
BarsLayout-Summary section
Bars = number Specifies the number of toolbars.

For example:
Bars=30
ScreenCX = resolution Specifies the user screen resolution on the X scale.

For example:
ScreenCX=1024
ScreenCY = resolution Specifies the user screen resolution on the Y scale.

For example:
ScreenCY=768
Plugin section
MTT<Version number> = path Specifies the path to the TestConductor DLL.
For example:
MTT4.1=L:\Rhapsody\v41\
TestConductor\
TestConductor.dll
Tornado section
DefaultTargetServerName = string Specifies the default target-server name used with Tornado.

Rational Rhapsody 199

Properties

Environment Variable Description

RecentFilesList section
File<#> = path Lists the .rpy files that have been loaded recently. The maximum
number of files listed is four.

For example:
File1=J:\Rhapsody5\ProjectAda\
NewFunc\NewFunc.rpy
File2=J:\Rhapsody5\CPPProjects\
NewFunc\NewStuff\NewStuff.rpy
File3=J:\Rhapsody41MR2\AdaProject\
Dishwasher\Dishwasher\Dishwasher.rpy

200 User Guide

 Format properties

Format properties
Rational Rhapsody uses properties under the Subject Format to determine the format used for
displaying various graphical elements.

These properties do not appear on the Properties tab of the Features window, but you can control
these formatting features using the Format window that is displayed when you select Format that
displays on the context menu for graphical elements. This window lets you set formatting options
up to the project level.

In some cases, you might want to set formatting options across multiple projects. This can be done
by overriding the value of formatting properties using the site.prp file.

These are the formatting properties that can be used.

DefaultSize - specifies the default size to use for graphical elements of this type. You can
change the default size for elements of a given type by selecting the New Element Size
check box in the Make Default window. In the value that is used for this property, the
third coordinate represents the width of the graphical element, and the fourth coordinate
represents the height of the element. For more information, see Defining default
characteristics.
Fill.FillColor - specifies the color to use to fill the background of the graphical
element. Corresponds to the Fill Color selector on the Fill tab of the Format window. For
more information, see Defining line characteristics.
Fill.Transparent_Fill - used to specify whether or not the fill should be transparent.
Corresponds to the Transparent Pattern check box on the Fill tab of the Format window.
Fill.BackgroundColor - used as the color of the superimposed pattern if you have
chosen a pattern to use for the fill. Corresponds to the Pattern Color selector on the Fill
tab of the Format window.
Fill.FillStyle and Fill.FillHatch - represent the fill pattern to use. Correspond to
the Pattern list on the Fill tab of the Format window.
Font.Font - specifies the font to use for the text on the graphical element. Corresponds to
the font list on the Font tab of the Format window.
Font.FontColor - specifies the color of the font to use for the text on the graphical
element. Corresponds to the Text Color selector on the Font tab of the Format window.
Font.Size - specifies the size of the font to use for the text on the graphical element.
Corresponds to the font size list on the Font tab of the Format window.
Font.Underline - specifies whether or not the text on the graphical element should be
underlined. Corresponds to the Underline check box on the Font tab of the Format
window.

Rational Rhapsody 201

Properties

Font.Strikeout - specifies whether strikeout text should be used for the text on the
graphical element. Corresponds to the Strike-Out check box on the Font tab of the Format
window.
Font.Weight - used for bolding of text on the graphical element. Corresponds to the bold/
italic control on the Font tab of the Format window.
Font.Italic - used for italicizing text on the graphical element. Corresponds to the bold/
italic control on the Font tab of the Format window.
Line.LineColor - specifies the color to use for the outline of the graphical element.
Corresponds to the Color selector on the Line tab of the Format window.
Line.LineStyle - specifies the style to use for the outline of the graphical element, for
example, solid or dotted. Corresponds to the Style list on the Line tab of the Format
window.
Line.LineWidth - specifies the width of the line to use for the outline of the graphical
element. Corresponds to the Width list on the Line tab of the Format window.

Defining default characteristics

To set default characteristics for an element type based on an existing element:

1. Right-click the element in a diagram that you want to use as the element pattern and select
Make Default.

2. In the Make Default window, select the Item characteristics to be copied from the
highlighted element to other elements of the same type:

Display Options
Format
New Element Size (for graphical elements only)
3. Select the Level in your project for all of the elements of that type to have the same
characteristics:

Diagram
Package
Project
4. Click OK.

202 User Guide

 Format properties

Defining line characteristics

To define the graphical appearance of a line in a diagram:

1. Right-click the line and select Format.

2. In the Format window on the Line tab, select the Line color, style, and width.

3. On the Font tab, select the font name and other text characteristics.

Rational Rhapsody 203

Properties

204 User Guide

 Rational Rhapsody projects

A Rational Rhapsody project includes the UML diagrams, packages, and code generation
configurations that specify the model and the code generated from it. The term project is
equivalent to model in Rational Rhapsody.

This section provides an overview of a Rational Rhapsody project, the components of a project,
and the procedures to create, edit, and store projects.

Project elements
A project consists of elements that define your model, such as packages, classes and diagrams. The
browser displays these elements in a hierarchical structure that matches the organization of your
model. Rational Rhapsody uses these elements to generate code for your final application.

A Rational Rhapsody project has the following top-level elements:

Components contain configurations and files and also hold the variants for different
software product lines.
Packages and profiles packages contain other packages, components, actors, use cases,
classes (C++/J), object types, events, types (C/C++), functions (C,C++), objects,
dependencies, constraints, variables, sequence diagrams, OMDs, collaboration diagrams,
UCDs, and deployment diagrams.

A profile “hosts” domain-specific tags and stereotypes.

UML diagrams For example, use case, object model, sequence, collaboration,
component, and deployment diagrams.
For more information about project elements, see Model elements.

Rational Rhapsody 205

Rational Rhapsody projects

Creating and managing projects

When working in Rational Rhapsody, you need to know the basic procedures for using a project.
You can create a new project, or work with an existing project. You can edit your project and save
the changes. You can create an archive of your project to easily exchange files with another
engineer or with customer support. You can have Rational Rhapsody create autosave files to
periodically store your unsaved changes, and automatically create backup projects of previously
saved versions. This section contains instructions for these and other procedures necessary for
using Rational Rhapsody.

Creating a project
When you create a new project, Rational Rhapsody creates a folder containing the project files in
the location you specify. The name you choose for your new project is used to name project files
and folders, and displays at the top level of the project hierarchy in the browser. Rational
Rhapsody provides several default elements in the new project to get you started, such as a default
component and configuration. Before you begin, create a project folder in your file system to hold
all of your Rational Rhapsody projects.

1. With Rational Rhapsody running, create the new project by either selecting File > New, or
clicking the New project button on the main toolbar.

2. Replace the default project name (Project) with <your project name> in the Project
name field. Enter a new directory name in the In folder field or Browse to find an
existing directory.

3. The Default Project Type provides all of the basic UML structures for most Rational
Rhapsody projects. However, you can select one of the specialized Profiles, that provide a
predefined, coherent set of tags, stereotypes, and constraints for specific project types.
4. You might want to select one of the Project Settings. For example, you might want to
work in a code centric setting instead of the default model centered setting.

5. Click OK. If the directory does not exist, Rational Rhapsody asks if you want to create it.
Click Yes to create the new project directory.

Rational Rhapsody creates a new project in the <your project name> subdirectory and opens the
new project. The project name in that directory is <your project name>.rpy.

206 User Guide

 Creating and managing projects

Profiles
A predefined Rational Rhapsody profile becomes part of your project in one of these ways:

You select an available profile from the Type pull-down menu, as described in the
Creating a project section.
You manually add a specialized profile to your project from the Share\Profiles directory,
as described in the Adding a Rational Rhapsody profile manually section.
Rational Rhapsody assigns a starting-point profile based on your project settings and
development environment.
The predefined profiles available to you depend on the system language and add-on products
licensed for Rational Rhapsody.

AdaCodeGeneration is the default Ada code generation profile.

AutomotiveC includes the capabilities provided in the following automotive industry
environments:
– FixedPoint arithmetic
– MainLoop (no-OS)
– OSEK21 and Basic/Extended OSEK task stereotypes
– MicroC
The AutomotiveC profilealso loads the StatemateBlock and SimulinkInC profiles.
For more information, see The Rational Rhapsody automotive industry tools.

AUTOSAR_21 and AUTOSAR_31 create automotive components in accordance with

the AUTOSAR development process using the ECU, Internal Behavior, SW Component,
System, and Topology diagrams. For more information, see AUTOSAR modeling. The
separate AUTOSAR profiles support the related AUTOSAR versions (2.1 and 3.1).
Note: AUTOSAR can only be used in C language projects.
CodeCentricCpp provides software developers an environment to work on C++
application code rather than development using models.
Default provides all of the basic UML structures for most Rational Rhapsody projects.
DoDAF is the Rational Rhapsody profile for DoDAF v1.0. For more information, see
Rational Rhapsody for DoDAF Add On and profile.
FixedPoint profile contains predefined types representing 8, 16, and 32-bit fixed-point
variables: FXP_8Bit_T, FXP_16Bit_T, FXP_32Bit_T. For more information, see Defining
fixed-point variables.
FunctionalC profile tailors Rhapsody in C for the C coder, allowing the user to
functionally model an application using familiar constructs such as files, functions, call
graphs and flow charts.

Rational Rhapsody 207

Rational Rhapsody projects

Harmony creates a project based on the Harmony (SE) Systems Engineering Process. For
more information, see Harmony process and toolkit.
IDFProfile uses the code generation settings for the Rational Rhapsody Developer for C
IDF. For more information, see Using IDF for a Rational Rhapsody in C project.
MARTE supports Model and Analysis for Real-Time Embedded systems that are not
covered by UML and annotates application models to support analysis by tools.
MODAF is the Rational Rhapsody profile for MODAF v1.1. For more information, see
IBM Rational Rhapsody MODAF Add On.
MicroC provides the facilities to run automotive C applications on systems with very
limited resources or with no operating system. For more information, see The MicroC
profile.
MISRA98 controls the code generation settings to comply with the MISRA-C 1998
standard.
NetCentric imports Web-services Definition Language (WSDL) files to design and
generate a services model. For more information, see Domain-specific projects and the
NetCentric profile. (This profile requires a separate license.)
RespectProfile can be used for C and C++ project to preserve the structure of the code
and preserves this structure when code is regenerated from the Rational Rhapsody model.
Meaning that code generated in Rational Rhapsody resembles the original. For more
information about handling regenerated code, see Code respect and reverse engineering
for Rational Rhapsody Developer for C and C++.
RoseSkin is used by Rational Rose Import to set format and other settings to resemble
Rational Rose look-and-feel.
SDL facilitates importing SDL Suite models into Rational Rhapsody SDL Blocks.
Simulink and SimulinkInC allow integration of MATLAB Simulink models into
Rational Rhapsody as Simulink Blocks (Simulink profile is for C++).
SPARK is the Rational Rhapsody Ada SPARK profile.
SPT (Scheduling, Performance, and Time) is an implementation of the SPT standard
(OMG standard) that specifies the method to add timing analysis data to model elements.
For more information, see Schedulability, Performance, and Time (SPT) profile.
StatemateBlock creates a new block/class allowing a Statemate model to become part of
a Rational Rhapsody architecture. This profile is only available for Rational Rhapsody in
C and requires a licensed version of Statemate 4.2 MR2 or greater with a license for the
Statemate MicroC code generator. For more information, see StatemateBlock in Rational
Rhapsody.
SysML supports both UML and SysML model diagrams for systems engineering. This
profile is the Rational Rhapsody implementation of the OMG SysML profile. For more
information, see Systems engineering with Rational Rhapsody.

208 User Guide

 Creating and managing projects

TestingProfile is an implementation of the OMG Testing Profile. The TestingProfile is for

use with Rational Rhapsody TestConductor. For more information about this profile, see
the third-party documentation provided for Rational Rhapsody TestConductor.
UPDM_L0 and UPDM_L1 are the Rational Rhapsody implementation of the OMG
UPDM L0 and L1 profiles that combine the MODAF and DoDAF profiles.

Opening an existing Rational Rhapsody project

To open an existing Rational Rhapsody project with all units loaded:

1. Choose File > Open. The Open window displays.

Note: To open one of the last-opened projects, select it from the list of projects that
appear on the File menu just above the Exit command.
2. In the Look in field, browse to the location of the project.

3. Select the .rpy file, or type the name of the project file in the File name field.

4. Select the With All Subunits check box. This causes Rational Rhapsody to load all units
in the project, ignoring workspace information. For information on workspaces, see Using
workspaces.

5. Click Open. The entire Rational Rhapsody project opens.

Search and replace facility

Engineers and developers can use the Rational Rhapsody Search and Replace facility for simple
search operations and to manage large projects and expedite collaboration work. The search results
display in the Output window with the other tabbed information.

This facility provides the following capabilities:

Perform quick searches

Locate unresolved elements in a model
Locate unloaded elements in a model
Identify only the units in the model
Search for both unresolved elements and unresolved units
Perform simple operations on the search results
Create a new tab in the Output window to display another set of search results
For more detailed instructions for the Search and Replace facility, see Searching in the
model.

Rational Rhapsody 209

Rational Rhapsody projects

Searching models
To search models:

1. With the model displayed in Rational Rhapsody, there are three methods to launch the
Search facility: select Edit > Search, click the binoculars button , or press Ctrl+F.

2. The Search window and perform a quick search. Type the search criteria into the Find
what field and click Find. The results display in the Output window. The search criteria
displays on the Search tab of the Output window.

3. To display the more detailed search window, select Edit > Advanced Search Replace or
click the Advanced button in the Search window (above). Both methods display this
window. The advanced search window provides the Unresolved and Units only search
features.

4. Select the Search elements tab to narrow the scope of the search to specific project
element types such as requirements, classes, packages, components, and diagram types.

5. Select the Search in tab to identify parts of the project for the search. Of course, you can
use combinations of selections on different tabs and the Find window to narrow your
search.

210 User Guide

 Creating and managing projects

6. The advanced search also includes these capabilities:

Exact string permits a non-regular expression search. When selected the search
looks for the string entered into the search field (such as char*)
Wildcard permits wildcard characters in the search field such as “*” produces
results during the search operation that include additional characters. For
example, the search *dishwasher matches class dishwasher and attribute
itsdishwasher.
Regular Expression allows the use of Unix style regular expressions. For
example, itsdishwasher can be located using the search term *dishwasher.
7. If after performing one search you want another Search tab with additional search results
displayed in the Output window, check the New Tab box in the Results in Output
Window area. Perform the next search.

Search results
After locating elements using the Search facility, you can perform these operations in the Search
window or in the Output window:

Sort items
Check the references for each item
Delete
Load
To sort items in the list, click the heading above the column to sort according to display that
feature of each item in the list.

Examining references in search results

To examine the references for an item in the search results:

1. Right-click an item in the search results list to display the menu.

2. Select References and examine the information displayed in the window, as shown in this
example:

Rational Rhapsody 211

Rational Rhapsody projects

Deleting located items

To delete an item located in search process:

1. Right-click an item in the search results list to display and then select Delete from Model.
The system displays a message for you to confirm the deletion.

2. Click Yes to complete the deletion process.

If you have located an unloaded item in the search results and want to load it into the model, right-
click the item. Load the item in the same manner as it is loaded from within the browser.

Replacing
If you want to replace item names or other terminology throughout the model:

1. Display the Advanced Search.

2. Enter the current terminology in the Find what field.

3. Enter the new terminology into the Replace with field.

4. Make any additional selections to limit the search and replace process.
5. Click Find and approve or skip the possible replacements.

212 User Guide

 Creating and managing projects

Locating and listing specific items in a model

During development you might need to examine a specific feature or create a list of items in the
model. This is one of the situations when the Rational Rhapsody Application accelerators keys are
useful.

In this example, the developer wants a list of the ports that are used by a specific interface.

To display a list of specific items in a Rational Rhapsody model:

1. Display the model in Rational Rhapsody.

2. If you need to locate the section you want to examine, you can use Search and replace
facility to find it. Then in the browser, select the item for which you need more
information.

3. In this example, press the Ctrl-R (for relationships) accelerator keys to list the relations
with the IDoorListener interface.

4. You can sort the displayed list by the Name or Type by clicking the heading of the
column. In this example, the items are sorted by Type to show the ports grouped together.

Note
You can also use ReporterPLUS to generate a report for a selected section of your model.

Rational Rhapsody 213

Rational Rhapsody projects

File menu commands

The File menu provides file management capabilities for the entire project. You can use the File
menu to create a New project, Open an existing Rational Rhapsody project, Save, Close files,
Print, and Exit the project as these features are typically used in Windows applications. The
Rational Rhapsody File menu also contains special project management features to insert other
files and projects and check files in and out of your configuration management (CM) system.
These features are also accessible from the Standard tools icons.

File > New

This menu command creates a new Rational Rhapsody project. See Creating a project.

File > Add to Model

Use this File menu command to insert an element into the active project.

File > Add Java API Library

Use this File menu command to import a Java API as a library that you want to use within the
project.

File > Configuration Items

Use this File menu command to launch Rational Rhapsody access to your configuration
management (CM) system to check files in and out and perform other CM operations.

File > Compare

If you have launched the Rational Rhapsody DiffMerge tool, the Compare menu command is
available from the DiffMerge File menu. This menu command allows you to browse and select
files to compare. You can compare files, list all of the differences, and merge the files if wanted.

214 User Guide

 Creating and managing projects

Editing and changing a project

You build projects in Rational Rhapsody by creating and defining elements using either the
browser or the graphic editors. Elements include components, packages, classes, operations,
events, diagrams, and so on.

Adding elements
To add elements from the browser:

1. Right-click an element, then select Add New. A submenu that lists all the elements that
can be added at the current location in the project hierarchy is displayed.

2. Select the element you want to add.

For detailed information about adding elements from the browser, see Model elements. To add
elements from a graphic editor, use the drawing tools to draw the element in the diagram. For
information on using the graphic editors, see Graphic editors.

Adding a Rational Rhapsody profile manually

To add another predefined Rational Rhapsody profile manually to your project:

1. Open the existing project.

2. Choose File > Add Profile to Model.

3. The Add to Profile to Model window lists all of your available profiles, either as separate
.sbs files or in folders.

4. Select a .sbs file for the profile and click Open. The system checks to be certain that the
selected profile is compatible with the language being used in the existing project.

Rational Rhapsody lists the newly added profile in the Profiles section of the browser. If you are
not familiar with the profile, open the profile in the browser to examine its characteristics.

Rational Rhapsody 215

Rational Rhapsody projects

Editing in the Features window

Each element in the project has features that can be edited using the Features window. The features
for an element include things like its name, description, type, and implementation code.

Double-click the element.

Right-click the element and then select Features.
Select an element in the browser, then type Alt + Enter.
For more information on using the Features window, see The Features window.

Undo and redo

Rational Rhapsody allows you to undo the last 20 operations, and to redo the operation that was
most recently undone.

To undo the last operation, do one of the following actions:

Choose Edit > Undo.

Click the Undo tool.
To redo an operation, do one of the following actions:

Choose Edit > Redo.

Click the Redo tool.
The Undo menu command does not become active until you perform at least one operation that
can be undone. Similarly, the Redo menu command is not active until you have used the Undo
command at least once.

By default, Rational Rhapsody allows you to undo the last 20 operations, but you can set this value
in the General::Model::UndoBufferSize property. Setting this property to a value of zero
disables the Undo/Redo feature.

You cannot use the Undo command after large operations that affect the file system. The undo
operation buffer is cleared and the Undo and Redo tools are deactivated. The following operations
cannot be undone:

Saving, opening, or closing a project

Automatic diagram layout
Roundtripping code with the “generated code in browser” option
Loading a unit into a workspace
Configuration management operations
Importing Rational Rose models
Reverse engineering

216 User Guide

 Creating and managing projects

Adding a file unit to the model (via the File > Add to Model command)
Code generation with the “generated code in browser” option

Using IDF for a Rational Rhapsody in C project

For some systems developed using Rational Rhapsody in C, the OXF provided with Rational
Rhapsody is not appropriate because the systems require a solution with a smaller footprint. To
provide a solution for these environments, a limited framework called IDF (Interrupt-Driven
Framework) is also provided with Rational Rhapsody.

Rational Rhapsody provides a base IDF model that can be adapted for different target systems.
Also included is a sample adaptation for Microsoft NT illustrating the use of the IDF.

To use this sample model to learn about the IDF:

1. Start the development version of Rational Rhapsody in C and choose File > Open and
browse to locate the IDF model Share\LangC\idf\model\idf.rpy.

2. With that project open, click the GMR button to generate and make the generic
configuration automatically displayed above the window, as shown here.

This generates all core files and idfFiles.list with dependencies and rules in the
Share\LangC\idf directory.

3. Using the same method, open another IDF model,

Share\LangC\idf\Adapters\Microsoft\MicrosoftNT.

4. Generate and make this model with the GMR button. This builds the library msidf.lib in
the directory Share\LangC\lib.

Saving a project
You can save a project in its current location using File > Save or click the Save button in the
toolbar. The Save command saves all modified files in the project repository.

Saving a project in a new location

To save the project to a new location with Save As:

1. Select File > Save As. The Save As window opens.

2. Use the Save In field to locate the folder where you would like to save the project.

Rational Rhapsody 217

Rational Rhapsody projects

3. Type a name for the project file in the window. The file extension .rpy (for repository)
denotes that the file is a Rational Rhapsody model.

4. Click Save. All project files are saved in the project repository.

Incremental save
If you want to save only the modified project units and not the entire project:

1. Select File > Project Properties and select the Properties tab.

2. Navigate to the General::Model::UseIncrementalSave property. This property should

be checked to use the incremental save feature.

Autosave
By default, Rational Rhapsody performs an incremental autosave every 10 minutes to back up
changes made between saves. Modified units are saved in the autosave folder, along with any units
that have an older time stamp than the project file. Modifications to the project file are saved in the
<Project>_auto.rpy file. When you save the project, the autosave files are cleared.

The autosave feature saves files in flat format. All unit files reside in the <Project>_auto_rpy
folder, regardless of the directory structure of the original model.

To change the autosave interval, use the General::Model::AutoSaveInterval property. The

interval is measured in minutes. To disable the autosave feature, set the AutoSaveInterval
property to 0.

218 User Guide

 Creating and managing projects

Renaming a project
To change the name or location of the project, use the Save As command. Do not attempt to edit
the project file directly. When you save the project under a different name, the name of the project
folder is updated in the browser.

Refactoring or renaming in the user code

To rename an element that is in the user code:

1. In the browser, right-click the element to be renamed and select Refactor > Rename.

2. Enter the New Name and click Continue.

3. Use the Find window to the element name.

Previewing the rename changes

Before the name changes are applied, the Rename Preview lists all of the references in the user
code that will be renamed.

1. Select entries in the lower section of the preview window to see the related code displayed
above.

2. To remove a reference from the list of changes, click the check box before the reference to
remove the green check.

3. To accept the checked changes, click OK.

Examining the renamed elements

After accepting the previewed changes, the rename text displays in the selected browser element.
To check the accuracy of the change:

1. Expand the browser tree to see the change to the related elements.

2. Display the Features window for the element and check the information to be certain it has
been changed as you expected.

Rational Rhapsody 219

Rational Rhapsody projects

Closing all diagrams

To close all the diagrams opened for a project, choose Window > Close All.

Closing a project
1. Select File > Close.

2. If you have unsaved changes, Rational Rhapsody asks if you would like to save your
changes before closing the project. Select one of the following options:

Yes saves the changes.

No discards the changes.
Cancel cancels the operation and return to Rational Rhapsody.

Closing Rational Rhapsody

To exit from Rational Rhapsody, select File > Exit.

Creating and loading backup projects

Rational Rhapsody can create backups of your model every time you save your project, allowing
you to revert to a previously saved version if you encounter a problem. To use the automatic
backup feature, set the General::Model::BackUps property to the number of backup projects you
want Rational Rhapsody to create. The options are None (default), One, and Two. Leave the
default value of None if you do not want Rational Rhapsody to create backups.

To set up automatic backups for your project:

1. In the browser, right-click the <project name> at the top of the browser list and select
Features.

2. On the Properties tab, click the All radio button to display all of the properties for this
project.

3. Expand the General and Model property lists and locate the BackUps property.

4. Select One or Two from the pull-down menu. With this setting, Rational Rhapsody creates
up to one or two backups of every project in the project directory.

5. Click OK.

220 User Guide

 Creating and managing projects

After this change, saving a project more than once creates <projectname>_bak2.rpy contains the
most recent backup and the previous version in <projectname>_bak1.rpy. To restore an earlier
version of a project, you can open either of these backup files.

1. Open the <Project>_bak2.rpy (or the <Project>_bak1.rpy file) in Rational

Rhapsody. Do not try to rename the backup file directly.

2. Save the project as <Project>.rpy using the File > Save As command.

Archiving a project
At times, you might need to archive a project to send it to another developer or to Customer
Support. To create a complete archive, include the following files and directories:

<Project>.rpy file
<Project>_rpy directory with all subdirectories
<Component> directories
Any external source files (.h and .cpp) needed to compile the project

Rational Rhapsody 221

Rational Rhapsody projects

Table and matrix views of data

Rational Rhapsody provides these additional methods to view model data:

Table view performs a query on a selected element type and displays a detailed list of its
various attributes and relations.
Matrix view displays queries showing the relations among selected model elements.
These views provide the following development capabilities:

Define and run dynamic queries of model content

Provide easy requirements display and analysis
Produce exportable and printable tables and data lists

Basic method to create views from layouts

To create either the table or matrix view, follow these general steps:

1. Select any area of the model in the Rational Rhapsody browser where you want to store a
table or matrix layout (query design).

2. Define a layout for the table or matrix (as described in the following sections) and save it
in the selected browser location.

3. Define a view of the model data using the previously defined layout. This view also gives
you the opportunity to define the scope of the query for the view.

4. In the browser, double-click the defined view to display the results of the query in the
drawing area.

5. To edit the data displayed in a view, use the Features window for the view and click the
Refresh button to update the view.

Note: Data displayed in views cannot be edited directly in a view. You must use the
Features window for a view to make your edits.
6. To export the data, right-click the data in the drawing area and select Copy.

222 User Guide

 Table and matrix views of data

Creating a table layout

To design the structure for your model elements query as a table layout:

1. Right-click the package in the Rational Rhapsody browser where you want to create and
store your table layout and select Add New > Table\Matrix > Table Layout.

Note: Add New > Table\Matrix is the default menu command structure in Rational
Rhapsody. It can be changed by users. This topic assumes that all defaults are
in place.
2. In the browser, enter a name for this table design. You might want to include the word
“layout” in the name to help identify your defined layouts from their generated views.

3. Double-click the new layout in the browser to open its Features window.

4. On the Element Types tab, select the element types you want to be displayed in the table:

5. Click Apply to save your selections without closing the Features window.

Rational Rhapsody 223

Rational Rhapsody projects

Adding a new row to the table layout

After Creating a table layout, you can begin to create the table design.

1. On the Columns tab, click the New button to create a new row in the table layout.

2. For the row, select a Type and Property from the corresponding menus for your query
purpose:

The General Attribute type might use one of the following properties (also
shown in the following figure) to define it:
– Name displays the name of an element.
– Description displays the description for an element (if there is one).
– Element type displays the element type of an element.
– From displays where an element is from.
– To displays where an element goes to.
– Via Port (From) displays the port from which a relation is connected.
Typically used along with Via Port (To). For more information, see Including
ports and multiple relations.
– Via Port (To) displays the port to which a relation is connected. Typically
used along with Via Port (From). For more information, see Including ports
and multiple relations.

The Requirement Attribute type might have either an ID or Specification

property.
The Flow Attribute type might have only Flow items as its property.

224 User Guide

 Table and matrix views of data

The Tag type has the <<Select>> property. Click it to open the Select Tag
window in which you can identify the information for the tag. Click OK.

3. Click the New button to add each row for your table. Use the Move Item Up and
Move Item Down buttons to arrange the order of the rows in your table layout.

4. Optionally, to remove a row from the layout, select it on the Columns tab and click the
Delete button .

5. When you have completed your design layout, click OK.

Rational Rhapsody 225

Rational Rhapsody projects

Creating a table view

After you have created one or more table layouts, to generate a table view of the model element
data based on your layout design:

1. Right-click a package on the Rational Rhapsody browser to which you want to add a table
view and select Add New > Table\Matrix > Table View.

Note: Add New > Table\Matrix is the default menu command structure in Rational
Rhapsody. It can be changed by users. This topic assumes that all defaults are
in place.
2. In the browser, right-click the new table view and select Features to open its Features
window.

3. Enter a Name for the view.

4. Select the name of a previously created table layout from the Layout drop-down list.

5. Select the scope for this view by selecting a package from the Scope drop-down list.

6. Clear or select the Include Descendants check box if you want to exclude or include the
descendants for the selected scope. For more information, see Including and excluding
descendants.

7. Click OK to save your table view.

8. To make changes to the displayed data, double-click a row in the table view and make the
changes in the Features window for that element.

9. If you have finished making changes, you can use either of the following actions:

Click Apply to save your changes in the Features window and then click the
Refresh button to display the new data in the view.
If you are done making changes, click OK.

Changing the layout for a generated table

You can also return to the table layout and make design changes. To redisplay the data in the
changed table view, click Refresh.

Including and excluding descendants

By default, table and matrix views include descendants in their scope because the Include
Descendants check box on the General tab of the table or matrix view’s Features window is
selected by default. For example, when you produce the table view whose scope is the main
package and both packages have objects, the default the view shows all descendants.

226 User Guide

 Table and matrix views of data

To exclude descendants from appearing in your table or matrix view, you need to clear the Include
Descendants check box on the General tab of the Features window for the particular view, as
shown in the following figure for a table view. Then (refresh the view if necessary), the view
shows without descendants.

Analyzing data in the table

In the browser, double-click the table view name to generate the results of the data query. The
query analyzes data for the selected package and all of its nested packages.

Adding elements to a table

After creating a table from the table layout, you might want to add new element type to the table.

1. On the left of the table display, click the Add model element icon.
2. In the Add new element window, select the Element type from the pull-down menu.

3. Select the Location from the pull-down menu.

4. Select the number of elements.

5. Click OK.

The revised table displays the new element automatically.

Rational Rhapsody 227

Rational Rhapsody projects

Creating a matrix layout

To create a matrix layout to analyze the relationships among model elements:

1. Right-click a package on the Rational Rhapsody browser where you want to add a matrix
layout and select Add New > Table\Matrix > Matrix Layout.

Note: Add New > Table\Matrix is the default menu command structure in Rational
Rhapsody. It can be changed by users. This topic assumes that all defaults are
in place.
2. In the browser, enter a name for this new matrix design.
You might want to include the word “layout” in the name to help identify your defined
layouts from their generated views.

3. Double-click the new matrix layout to open its Features window.

4. On the Cell Element Types tab select only one of the possible element types. Cell element
type is the relation type between the “From” and “To” elements to be displayed in matrix
cells. In the finished matrix, the elements of that type are displayed down the left side of
the matrix view to identify a row of data.

5. Click Apply to save your selections and keep the Features window open to select the
“From” and “To” elements.

228 User Guide

 Table and matrix views of data

Selecting the element types for the matrix layout

After selecting the Cell Element Types in the Features window for the matrix layout, define the
basic “from” and “to” structure for the matrix:

1. On the From Element Types tab, select the element types from which the connection
should be identified.

2. Click Apply to save your selections.

3. On the To Element Types tab, select the element types to which the connection should be
identified.

4. Click OK.

Modifying the matrix layout

You can return to the matrix layout and make changes to the design even after the data has been
generated in the matrix view. To redisplay the data in a modified view, use the Refresh icon on the
matrix view.

Rational Rhapsody 229

Rational Rhapsody projects

Creating a matrix view

To create a matrix view to analyze the attributes of the model elements you identified in the matrix
layout:

1. Right-click the package on the Rational Rhapsody browser to which you want to create
and store a matrix view and select Add New > Table\Matrix > Matrix View.

Note: Add New > Table\Matrix is the default menu command structure in Rational
Rhapsody. It can be changed by users. This topic assumes that all defaults are
in place.
2. In the browser, right-click the new matrix view and select Features to open its Features
window.

3. Enter a Name for the new matrix view.

4. Select the name of a previously created matrix layout from the Layout drop-down list.

5. Select the scope for this view by selecting a package or project in the “From” Scope and
in the “To” Scope drop-down lists, as shown in this example:

6. Clear or select the Include Descendants check box if you want to exclude or include the
descendants for the selected scope. For more information, see Including and excluding
descendants.

7. Click OK to save your matrix view.

230 User Guide

 Table and matrix views of data

8. In the browser, double-click the matrix view name to generate the results of the data query.
The query analyzes data for the selected package and all of its nested packages, as shown
in this example:

9. To make changes to the displayed data, double-click a cell in the matrix view and make
the changes in the Features window for that element.
10. Depending on if you are done making changes:

Click Apply to save your changes in the Features window and then click the

Refresh button to display the new data in the view.

If you are done making changes, click OK.

Rational Rhapsody 231

Rational Rhapsody projects

Filtering out rows and columns without data

If you want to remove the rows in a matrix view that do not contain data:

1. Open the Features window for the view or choose File > Project Properties to display the
properties for your project. For information about using properties in your project, see
Properties.

2. On the Properties tab, locate the Model::MatrixView::HideEmptyRowsCols property

and select its check box.

3. Click OK.

4. When you display a view, click the Toggle empty rows filter button to show only the
rows containing data.

If you select the Model::MatrixView:HideCellNames property, the content of a cell is displayed

only with an icon.

232 User Guide

 Table and matrix views of data

Including ports and multiple relations

By default, the table view and matrix view show relations between objects (even if ports are
involved) and display multiple relations between elements if they exist. This means that you can
easily communicate your design information in a tabular or matrix format.

The Model::TableLayout::ShowContainerElementForPorts property controls this capability.

By default, this property is set to Checked. This means that for table views, if ports are
encountered when searching for connections of relations, Rational Rhapsody displays the port’s
parent element instead of the port itself. For matrix views, Rational Rhapsody automatically looks
at child ports of elements and finds the relations to other elements.

If you do not want this property to be active, you would clear the check box for it.

To make changes to this property:

1. Open the Features window for the table view or matrix view.

2. On the Properties tab, locate the Model:TableLayout:ShowContainerElementForPorts

property.

3. Clear or select the check box next to the property name.

Clear it to disable this property.

Select it if you want to show relations between objects (even if ports are involved)
and display multiple relations between elements if they exist. This is the default.
4. Click OK.

Note
When there are multiple relations, options such as Features, Locate, and so on are disabled.

Adding elements to a matrix

After creating a matrix from the matrix layout, you might want to add new element type.

1. On the left of the matrix display, click the Add model element icon.

2. In the Add new element window, select whether you want the element selection to be
Based on row settings or Based on column settings.

3. Select the new Element type from the pull-down menu.

4. Select the Location from the pull-down menu.

5. Select the number of elements.

6. Click OK.

Rational Rhapsody 233

Rational Rhapsody projects

The revised matrix displays the new element type’s information automatically.

Setting up an initial layout for table and matrix views

You can bind a view and layout for a table or matrix through the use of a New Term stereotype that
has the Model::Stereotype::InitialLayoutForTables property set for this purpose for a
Rational Rhapsody profile. Once you apply the stereotype to a table or matrix layout, it allows you
to set the initial layout for a table or matrix view.

To apply a stereotype to a table or matrix layout for a profile:

1. Create a profile. For more information, see Creating a customized profile.

2. Create a table or matrix layout and design it as you want. See Creating a table layout and
Creating a matrix layout.

3. In your profile, create a stereotype and define it as a New Term and to what it is applicable
to (table view or matrix view, as shown in the following figure) and click Apply to save
but not close the window. For information on stereotypes, see Stereotypes.

4. On the Properties tab, locate the Model::Stereotype::InitialLayoutForTables

property and enter the name of the layout you created in Step 2 and click OK.
5. Create a table or matrix view through the profile, select Add New > [name of profile] >
[matrix view].

6. Open the Features window for the table or matrix view you created in the previous step
and note that the layout is already identified (because of the applicable stereotype).

234 User Guide

 Table and matrix views of data

7. Complete your design of the view by filling in the Scope boxes, as shown here, and click
OK.

8. Look at the Rational Rhapsody browser and notice that the view you just created is listed
in a View category (in our example, MyMatrixViewStereotypes, as shown in the
following figure) other than the general Matrix Views category, which only lists those
views that were created without a stereotype (using Add New > Table\Matrix > Matrix
View):

Rational Rhapsody 235

Rational Rhapsody projects

9. When you double-click the table or matrix view (MyMatrixView in our example above),
it shows the query results from the layout that has the specified stereotype.

Managing table or matrix data

After creating a table or matrix, you have additional options to manage a view and its data.
Right-click the view in the drawing area to display a menu with these standard Rational Rhapsody
options:

Features to open the Features window. For more information, see The Features window.
Locate to find the location of the element on the Rational Rhapsody browser.
Add to Favorites to add to your favorites list in Rational Rhapsody. For more
information, see The Favorites browser.
Browse from Here to open a Rational Rhapsody browser that contains a more-focused
Rational Rhapsody browser from whichever point you are at. For more information, see
Opening a Browse From Here browser.
The remaining options are standard Windows options. You might find the Copy option particularly
useful to export the view’s data into Microsoft Excel and then save it as a .csv file.

236 User Guide

 The Rational Rhapsody specialized editions

The Rational Rhapsody specialized editions

In addition to the Rational Rhapsody Developer edition that supports projects in C, C++, Java, and
Ada, Rational Rhapsody also provides three editions to create specialized projects:

Rational Rhapsody Designer for Systems Engineers edition

Rational Rhapsody Architect for Systems Engineers edition
Rational Rhapsody Architect for Software edition
For information about installing or switching between these editions, see the Rational Rhapsody
installation instructions.

Creating projects in Rational Rhapsody Designer for Systems

Engineers
To create a project in Rational Rhapsody Designer for Systems Engineers:

1. With Rational Rhapsody Designer for Systems Engineer running, create the new project
by either selecting File > New or clicking the New project button on the main toolbar.

2. Replace the default project name (Project) with <your project name> in the Project
name field. Enter a new directory name in the In folder field or Browse to find an
existing directory.

3. The Default Project Type provides all of the basic Rational Rhapsody Designer for
Systems Engineers edition features. However, you can select one of these specialized
Profiles to supply a predefined, coherent set of tags, stereotypes, and constraints for
specific project types:

DoDAF
FunctionalC
Harmony
MODAF
SPARK
SysML
TestingProfile
4. You might want to select one of the Project Settings. For example, you might want to
work in a code centric environment instead of the default model centered setting.

5. Click OK. If the directory does not exist, Rational Rhapsody asks if you want to create it.
Click Yes to create the new project directory.

Rational Rhapsody 237

Rational Rhapsody projects

The default Designer for Systems Engineers edition project contains a structure diagram as the
starting point. For more detailed instructions, see the Structure diagrams section.

Note
Remember that Designer for Systems Engineers can use any of the supported languages:
Ada, C, C++, or Java.
You can add the following profiles to a Designer for Systems Engineers project using the Adding a
Rational Rhapsody profile manually procedure:

AdaCodeGeneration
Backward compatibility profiles

JavaDoc
NetCentric
SDL
Simulink
SPT
For ideas for your project, examine the sample projects in following <Rational Rhapsody
installation path>\Samples:

Ada, C, C++, or Java Samples

Extensibility Samples
JavaAPI Samples
System Samples

238 User Guide

 The Rational Rhapsody specialized editions

Creating projects in Rational Rhapsody Architect for Systems

Engineers
Rational Rhapsody Architect for Systems Engineers does not include code generation or reverse
engineering. You use the same method to create projects as you do for Developer projects, but a
specialized project structure is created for systems engineers.

To create an Rational Rhapsody Architect for Systems Engineers project:

1. With Rational Rhapsody Architect for Systems Engineers edition running, create the new
project by either selecting File > New or clicking the New project button on the main
toolbar.

2. Replace the default project name (Project) with <your project name> in the Project
name field. Enter a new directory name in the In folder field or Browse to find an
existing directory.

3. The Default Project Type provides all of the basic Rational Rhapsody Architect for
Systems Engineers edition features. However, you can select one of this limited set of
specialized Profiles:

DoDAF
FunctionalC
Harmony
MODAF
NetCentric
SysML
4. You might want to select one of the Project Settings. For example, you might want to
work in a code centric environment instead of the default model centered setting.

5. Click OK. If the directory does not exist, Rational Rhapsody asks if you want to create it.
Click Yes to create the new project directory.
The basic default Architect for Systems Engineers edition project contains a structure diagram as
the starting point. For detailed instructions, see the Structure diagrams section.

Note
Remember that Rational Rhapsody Architect for Systems Engineers edition does not use
any of the four development languages available in other Rational Rhapsody editions.

Rational Rhapsody 239

Rational Rhapsody projects

Creating projects in Rational Rhapsody Architect for Software

Rational Rhapsody Architect for Software edition allows you to create a C, C++, or Java project
and also allows you to generate code frames for the project from a code generation menu.
However, the Architect edition does not support animation or code generation for ports and
statecharts. Many architects create a Rational Rhapsody Architect project and reverse engineer
code to use as a starting point. If a build environment is wanted for the project, the architect can
use Eclipse or another IDE.

To create a Rational Rhapsody Architect for Software project:

1. With Rational Rhapsody Architect for Software edition running, create the new project by
either selecting File > New or clicking the New project button on the main toolbar.

2. Select the primary implementation language as C, C++, or Java and click Next.
3. In the New Project window, replace the default project name (Project) with <your
project name> in the Project name field. Enter a new directory name in the In folder
field or Browse to find an existing directory.
4. The Default Project Type provides all of the basic Rational Rhapsody Architect for
Software edition features. However, you can select one of the specialized Profiles, that
provide a predefined, coherent set of tags, stereotypes, and constraints for specific project
types. The following profiles available for a new Architect project from the Type
selection:

CodeCentricCpp
FunctionalC
Harmony
NetCentric
SysML
You can also add the available profiles to Rational Rhapsody Architect for Software
project using the Adding a Rational Rhapsody profile manually procedure.

5. You might want to select one of the Project Settings. For example, you might want to
work in a code centric environment instead of the default model centered setting.

6. Click OK. If the directory does not exist, Rational Rhapsody asks if you want to create it.
Click Yes to create the new project directory.

For ideas for your project, you can examine the sample projects in these <Rational Rhapsody
installation path>\Samples directories.

240 User Guide

 Components with variants for software product lines

Components with variants for software product lines

If your company uses variations of the software to create a software product line,
component variants can manage the reuse of common components and generate code for
the product line.

Creating variation points

To create a software product line, identify the Rational Rhapsody components that are the
variation points for the system.

1. In a high-level object model diagram, create a class or object for the variable component.

2. In the Features window for each variable component, select VariationPoint as the
Stereotype. In this example, the jet and heater are the variation points for the dishwasher.

Rational Rhapsody 241

 Rational Rhapsody projects

Defining variants
To define one variant for each variation point:

1. For each variation point, draw its dependencies to the variant class or object.

2. For each variant class or object, display the Features window, and select Variant as the
Stereotype.

3. Complete the definition of the variant classes and objects to meet the requirements.

In this example, each variation point has two variants. Note that each of the classes and objects
contains a statechart to define the operation states.
.

The <<Static>> stereotype (on inheritance) duplicates all features of the static base class into the
static derive class including types, operations, attributes, associations, inheritances, ports,
dependencies, behavior and links.

242 User Guide

 Components with variants for software product lines

Selecting a variant
To select a variant:

1. Highlight the component.

2. Display the Features window and click the Variation Points tab.

3. Select the variant from the list.

Generating code for software variations

When code is generated, each component generates the specific mapping from the variation points
to their selected variants.

Rational Rhapsody 243

Rational Rhapsody projects

Multiple projects
Rational Rhapsody allows you to have more than one project open at a time. When you have more
than one project open, you can use the Rational Rhapsody browser to copy and move elements
from one project to another.

The following terms are used in Rational Rhapsody in the context of working with multiple
projects:

Projects is the top-level container (or folder) for all open projects in a Rational Rhapsody
session (saved as an .rpl file). The Projects folder contains the list of projects, which can
be saved and reopened.
Active Project is the project that you can currently be modify. This is also the project to
which Rational Rhapsody commands, such as for code generation, are applied (unless the
command opens a window that allows you to specify which project to use).

Inserting an existing project

To insert an existing project into an open project:

1. Open the existing Rational Rhapsody project into which you want to add another Rational
Rhapsody project.

2. Choose File > Insert Project.

3. Select Existing to insert a previously created Rational Rhapsody project for a directory.

Note: Rational Rhapsody does not permit two projects with the same name to be
incorporated.
The Rational Rhapsody browser displays a project list node called Projects that is one level above
the open projects. The currently active project name is in bold print, as shown in the following
example.

244 User Guide

 Multiple projects

Inserting a new project

To insert a new project into an open project:

1. Open the existing Rational Rhapsody project into which you want to add another Rational
Rhapsody project.

2. Choose File > Insert Project > New to open the window for Creating a project

Note: Rational Rhapsody does not permit two projects with the same name to be
incorporated.

Setting the active project

When you select File > Insert Project, the project you select automatically becomes the active
project.

Once you have more than one project open, you can make any project the active project as follows:

1. Right-click the project name in the Rational Rhapsody browser.

2. Select Set as Active Project.

Similar to the display of the active component and active configuration, the name of the active
project displays in bold in the browser.

You can modify an active project’s model elements only. (Rational Rhapsody displays RO, for read-
only, next to all project names in the browser that are in non-active projects.)

If you make a project active without first saving changes made to the previously active project, the
system asks you if want to save those changes. If you click the No button, your changes to the
previously active project are not yet lost. This is because when you close all the projects, the
system asks if you want to save the project list and all its projects. If you click the Yes button, all
changes made to all projects that have not been saved are saved at this time.

In general, Rational Rhapsody commands are applied only to the active project. However, the
commands Search and Locate in Browser can be applied across all open projects.

Rational Rhapsody 245

Rational Rhapsody projects

Copy and reference elements among projects

When you have more than one project open, you can use the Rational Rhapsody browser to copy
elements from one project to another using either of these methods:

Referencing an element in another project only “links” that element to the original
element in the original project
Copying creates a element in another project that is the same as the original

Note
Copying and referencing can only be done within the browser. You cannot drag an element
from one project to a diagram in another project.
You can use either the standard Windows copying techniques, as described in Copying elements to
other projects or the Shift key method, as described in Using the Shift key to copy, reference, or
move elements.

Creating references
Only elements that have been saved as units can be referenced in other projects.

To create a saved unit from an element:

1. In the active project, right-click the element in the browser and select Create Unit.

2. Type the Unit Filename if you want to use a different name from the displayed name.

3. Click OK to create the unit and the icon of the new unit is marked with a red box. In this
example, the homeowner and intruder elements are units.

4. In the project that is going to receive the reference, right-click the project name and select
Set as Active Project.

5. In the browser of the now active project, right-click the element that needs to reference the
new unit and then select Create Unit to change the receiving element into a unit.

246 User Guide

 Multiple projects

6. In the original project, select the unit that is being referenced. Click and drag that unit to
the active project’s new unit. When the reference is established, the (REF) symbol
displays next to the referenced element, as shown in this example:

Copying elements to other projects

To copy an element to another project:

1. In the browser, right-click the project name in the Rational Rhapsody browser from which
you are copying an element and select Set as Active Project.

2. Select the element you want to copy into the other project and select Edit > Copy or right-
click and select Copy.
3. Right-click the project name to which you are copying the element and select Set as
Active Project.

4. Select the folder where you want to store the copied element and select Edit >Paste. If the
copied element has the same name as an existing element in the new project, the name is
appended with “_copy.”

Copied elements with the same name as existing elements should be renamed to avoid confusion.

Using the Shift key to copy, reference, or move elements

To use the pop-up menu to copy, reference, or move a unit:

1. Be certain that the element has been saved as a unit, as described in Creating references.

2. In the non-active project, press and hold the Shift key, and click-and-drag the unit you
want to copy, reference, or move to the target project.

3. On the pop-up menu that displays, select the applicable command:

Copy here
Reference here, or
Move here - leave a reference

Rational Rhapsody 247

Rational Rhapsody projects

Moving elements among projects

To move an element from one project to another:

1. If the element to be moved is not a saved unit, save it as a unit.

2. Press and hold the Alt key, then click-and-drag the element to the other project.

3. Rational Rhapsody checks if there will be unresolved elements in the target project as a
result of the move. If there are unresolved elements, a message box displays along with
the Output window.

4. If you click Yes on the message box, the unit moves to the target project.

Note
The original unit, that was moved, now has a (REF) tag in the source project because the
unit has been moved and the moved unit is now the unit of record in the active project.

Closing all open projects

To close all of the projects that are currently open, select File > Close.

Managing project lists

When a number of projects are open at the same time, you can save the list of projects as a
Rational Rhapsody project list (.rpl) file.

Saving projects in a project list file

To save the project list, select File > Save All.

A new .rpl file is created in the current active project folder. The name of the project list file will
be Projects.rpl. (If a file with this name already exists in the folder, a number will be added to
the end of the file name, for example Project1.rpl.)

The current active project is saved as an attribute of the project list, so when you reopen a project
list, the active project will be the project that was active when the project list was last saved.

248 User Guide

 Multiple projects

Opening a project file list

After a project file list has been saved, you can re-open all the projects in a project list as follows:

1. Open the Open window, choose File > Open.

2. If necessary, look in the path for your project, then select the relevant project list file.
Typically, the Open window displays all .rpy and .rpl files.

3. Click Open.

Adding a project to a project list file

If you open a project list file, its contents are updated each time you select Save All. Therefore, to
add another project to a project list:

1. Select File > Insert Project and choose the project to add.

2. Decide if the just added project or another one should be the current active project.

3. Select File > Save All.

Removing a project from a project list file

To remove a project from a list of files:

1. In the Rational Rhapsody browser, select the project to remove.

Note that you cannot remove the current active project.

2. Press the Delete key on your keyboard.

3. Click Yes to confirm your action.

4. Select File > Save All.

Project limitations
The following items identify multiple project work and display limitations.

New project
You cannot add a new project to a list of open projects. When you select File > New, if there are
changes to be saved, you will be asked if you want to save before closing, then all open projects
will be closed, and the project list will be saved before the New Project window displays.

Rational Rhapsody 249

Rational Rhapsody projects

Placement of GUI elements

Information regarding the placement of elements such as toolbars and the browser window are
stored in the rhapsody.ini file, and are, therefore, uniform for all projects and project lists.
Information regarding the placement of elements such as windows are stored in a project’s
workspace file (.rpw). Therefore, these elements will change, depending on which project in the
list is currently the active project.

References window
The References window includes the references for all of the projects in the project list, and not
just those for the active project.

DiffMerge
DiffMerge does not support the comparison of project lists (that is, groups of projects).

Configuration management
Rational Rhapsody does not support the configuration management of project lists but you can use
your configuration management tool directly for a project file list.

Properties
When viewing properties, Rational Rhapsody always displays the property values of the selected
project. However, for all properties that affect more than one project, Rational Rhapsody uses the
settings of the active project. For information about using properties in your project, see
Properties.

Components and configurations

When you select a different project to be the active project, the Code toolbar displays the active
component and configuration for that project. The list of components/configurations available is
also updated accordingly.

VBA editor and the active project

When you open the Rational Rhapsody VBA Interface editor, you see only the items belonging to
the active project.

250 User Guide

 Naming conventions and guidelines

Naming conventions and guidelines

To assist all members of your team in understanding the purpose of individual items in the model,
it is a good idea to define naming conventions. These conventions help team members to read the
diagram quickly and remember the model element names easily.

Note: Remember that usually the names used in the Rational Rhapsody models are
going to be automatically written into the generated code. Therefore, the names
should be simple and clearly label all of the elements, and they should not use
any special characters.

Guidelines for naming model elements

The names of the model elements should follow these guidelines:

Class names begin with an upper case letter, such as System.

Operations and attributes begin with lower case letters, such as restartSystem.
Upper case letters separate concatenated words, such as checkStatus.
The same name should not be used for different elements in the model because it will
cause code generation problems. For example, you should not have a class, an interface,
and a package with the same name of Dishwasher.
Note the following about special characters:
– Do not include special characters in an element’s name if the element is used
for code generation.
– You can use special characters in the labels for model elements. See
Descriptive labels for elements.
– The following elements are the only ones for which you can include special
characters: Dependencies, Stereotypes, Flows, Links, Configurations, Table
layouts, Table views, Matrix layouts, Matrix views, Requirements, Actors,
Use Cases, and all diagrams.
– You can use the General::Model::NamesRegExp property to control what
special characters are allowed. For detailed information on a property, see
the definition displayed in the Properties tab of the Features window. For
information about using properties in your project, see Properties.
– While you can use spaces (but not special characters) in the names for actors,
it is not typical because the spaces might cause problems during code
generation.

Rational Rhapsody 251

Rational Rhapsody projects

Standard prefixes
Lower and upper case prefixes are useful for model elements. The following list shows common
prefixes with examples of each:

Event names = “ev” (evStart)

Trigger operations = “op” (opPress)
Condition operations = “is” (isPressed)
Interface classes = “I” (IHardware)

252 User Guide

 Using project units

Using project units

In Rational Rhapsody, a unit is any element of a project that is saved in a separate file. You can
partition your model into units down to the class level. Creating units simplifies collaboration in
team environments. With this feature, you have explicit control over file names and modification
rights, and you can check unit files in and out of a configuration management system.

Note
Association ends and ports cannot be saved as units.
The project and all packages are always units. The following table lists other project elements that
can be units.

Element File Extension Unit by Default?

Actors .cls No
Components .cmp Yes
Packages .sbs Yes
Classes .cls No
Implicit objects (parts) .cls No
Files .cls No
Diagrams (except statecharts Block definition diagrams No
and activity diagrams) (*.omd)
Component diagrams (*.ctd) No
Collaboration diagrams (*.clb) No
Deployment diagrams (*.dpd) No
Internal block diagrams No
Object model diagrams (*.omd) No
Sequence diagrams (*.msc) No
Structure diagrams (*.std) No
Use case diagrams (*.ucd) No

Rational Rhapsody 253

Rational Rhapsody projects

Unit characteristics and guidelines

The following unit characteristics and guidelines might help you use units effectively in your
projects:

A unit can be part of only one Rational Rhapsody model. Therefore, a unit can be
modified in only one Rational Rhapsody model.
A unit can be referenced as often as necessary.
A unit can contain many subunits.
Each model element is identified by a Global Unique Identifier (GUID), so each unit is
unique in its model.
Only model elements that must be shared should be changed into units.
A unit’s name should be the same as its model element name. This simplifies the
association between a unit and its model element.
Changing many model elements to units might slow Rational Rhapsody processes.
To create diagrams automatically as units, change the
General::Model::DiagramIsSavedUnit property to be Checked. The default is
Unchecked.

254 User Guide

 Using project units

Separating a project into units

If you need to share units in one project with another or you need to control some model elements
in a configuration management system, you might need to divide the project into units. Keep in
mind the Unit characteristics and guidelines.

To change elements to units:

1. Right-click the element and then select Create Unit. The Unit Information window for the
element opens with fields filled in, as shown in the following figure:

2. By default, the Store in separate file check box is selected.

3. Edit the default Unit Filename, if wanted. Rational Rhapsody assigns the appropriate file
extension for you in the next field. The Rational Rhapsody File Extension is displayed
and cannot be changed if the unit must have a specific extension for Rational Rhapsody.

4. You change the Directory for the new unit.

5. In the access privileges radio button area, you might want to change the default Read/
Write selection for the new unit to Read Only or External Reference.

6. The Include in next load selection is automatically checked since you are adding a unit.

7. Click OK.
The unit in the browser is now marked with a small red icon. Save the unit and the icon turns
black.

Rational Rhapsody 255

Rational Rhapsody projects

Modifying units
To modify a unit:

1. In the browser, right-click the unit to modify, then select Unit > Edit Unit. The Unit
Information for Package window opens.

2. Change the settings as wanted.

3. Click OK.

To reduce the amount of time required to save a project, Rational Rhapsody marks all modified
units and enables you to save those units without saving the entire project. To indicate that a unit
has changed, the unit icon in the browser changes from black to red.

Saving individual units

To save a selected unit:

1. Select the unit in the browser.

2. Right-click the unit and select Unit > Save Unit.

Loading and unloading units

When you open a Rational Rhapsody project, the Open window allows you to specify whether or
not Rational Rhapsody should load the subunits contained in the project. If you need to locate the
unloaded units in a project, you can use either of these tools:

Rational Rhapsody browser menu options for the Unloaded Units

Search and replace facility
If you elected to load the project without its subunits, you can later load individual subunits:
Right-click the subunit in the browser to display the menu and select Load [unit name], or select
Load [unit name] with Subunits to load the unit together with all its subunits.

To unload a unit, right-click the subunit in the browser and select Unit > Unload [unit name].

Units that are not currently loaded are indicated by (U) before the unit name in the browser.

If you do want to unload a unit, but you want to prevent it from being loaded the next time you
open the project:

1. In the browser, right-click the unit and select Unit > Edit Unit.

2. On the Unit Information, clear the Include in next load check box.

256 User Guide

 Using project units

Loading units from last session

If you would like to load only those units that were open during your last Rational Rhapsody
session, select the Restore Last Session radio button when you open the project with the Open
window.

If you open the project by selecting its name from the MRU list (under File), Rational Rhapsody
will also only load those units that were open when you completed your last session.

Note
This applies also to the Include in next load check box. If you cleared this check box,
Rational Rhapsody will refrain from loading the unit only if you select the Restore Last
Session radio button when you open the project, or open the project from the MRU list.

Rational Rhapsody 257

Rational Rhapsody projects

Saving packages in separate directories

To assist with configuration management and improve project organization, you might want to
store packages in separate subdirectories within a parent folder. Rational Rhapsody has two
directory schemes:

In flat mode, all package files are stored in the project directory, regardless of their
location in the project hierarchy.
In hierarchical mode, a package is stored in a subdirectory one level below its parent. It is
possible to have a hybrid project, where some packages are stored in flat mode, and others
are organized in a hierarchy of folders.
To set the default so that new packages are stored in separate directories:

1. Select the <ProjectName> at the top of the browser hierarchy.

2. Right-click and select Features.

3. Locate the General::Model properties and select the DefaultDirectoryScheme property.

4. Change the value from flat to PackageAsDirectory.

Flat mode
In flat mode, Rational Rhapsody stores all package files in one directory. This is usually the project
directory.

If you are changing modes from hierarchical to flat, Rational Rhapsody maintains the existing
directory structure, but does not add any new subdirectories. New packages are stored within the
existing structure beneath the directory of their closest parent.

To create a new model that will be in one file, after you create the project, set the following
properties’ check boxes to be Cleared at the project level:

General::Model::BlockIsSavedUnit
General::Model::ClassIsSavedUnit
General::Model::ComponentIsSavedUnit
General::Model::DiagramIsSavedUnit
General::Model::FileIsSavedUnit
General::Model::ObjectIsSavedUnit
General::Model::PackageIsSavedUnit

258 User Guide

 Using project units

Hierarchical mode
In hierarchical mode, you can save a package in a unique subdirectory one level below the
directory of its parent. All units contained in the package are saved in its subdirectory, along with
the package (.sbs) file. Nested packages are further divided into subdirectories.

Consider the example of a project Home that contains the package Family, which contains the
package Pets. With each package in its own directory, the path of the Pets.sbs file would be:
../Home/Family/Pets/Pets.sbs

Note
When changing from flat mode to hierarchical mode, Rational Rhapsody does not
automatically create folders for existing packages. Instead, it creates a folder for each new
package within the existing directory structure.
1. Right-click the package and select Unit > Edit Unit. The Unit Information for Package
window opens.

2. Select the Store in separate Directory check box (available only for packages). The name
of the separate directory has the same name as the unit.
3. Click OK.

Rational Rhapsody creates the new directory and moves the package, along with all of its subunits,
into the new folder.

Changing a hierarchical model to a flat model

To change an existing model from hierarchical mode to flat mode, write a VBA script that iterates
over the entire model and, for each IRPUnit, calls the setSeparateSaveUnit(true) method.
The only unit that should not activate this method is the project.

Rational Rhapsody 259

Rational Rhapsody projects

Using environment variables with reference units

If you have a reference unit in your model (added using Add to Model As Reference), you can
edit its location using the Directory field of the Unit Information window, and use an environment
variable as part of that location.

Note
When you add a reference to your model, Rational Rhapsody adds the packages as top-level
packages by default. However, you can move the reference packages so they become nested
packages.
For example, you can use a relative path (..\) or the environment variable $ENV_VAR. If you set
the General::Model::EnvironmentVariables property to include the path of this environment
variable, Rational Rhapsody parses and executes that environment variable when it opens the
project, and then searches for the reference unit in the specified location.

Note
If you use relative paths, note that the path is relative to the _rpy folder, not where the .rpy
file is located.

260 User Guide

 Using project units

Preventing unresolved references

When you delete an element that has references in read-only files, those references cannot be
updated accordingly on the disk because the files are read-only files. These references become
unresolved when the model is reloaded. In order to resolve this situation, read-only files that
contain references to elements that you are deleting should be made writable before you perform
the delete operation.

Rational Rhapsody automatically opens the References in Read-Only Files Encountered window
when it detects that an attempt to delete an element might cause unresolved references. When you
delete an element (for example, through the Rational Rhapsody browser or a graphic editor) that
has references in read-only files, the References in Read-Only Files Encountered window opens
with a list of read-only files that contains references to the deleted element.

The following options are available to you on this window:

Check out the selected and continue - Use only if you have a configuration management
tool set.
Note: This option might fail if the unit you are trying to check out is not already
checked in.
Note: This option is unavailable in the Rational Rhapsody Platform Integration.
Make the selected files read/write and continue
Ignore the references in read-only files and continue. Using this option means that
unresolved references might be created when the model is reloaded.

Rational Rhapsody 261

Rational Rhapsody projects

Using workspaces
Workspaces enable you to work with selected units of a project without having to open the entire
model. This feature supports component-based development and collaboration among teams. It
also reduces the time required for routine operations, such as saving and code generation, by
enabling you to load only the units currently under development.

In addition, workspaces save viewing preferences, including window size, position, status of
feature windows, and the scaling or zoom factor of open diagrams.

Rational Rhapsody automatically saves workspace information in a separate file named

<Project>.rpw. Rational Rhapsody saves the .rpw file whenever a project is closed, regardless of
whether you save the project itself.

Creating a custom Rational Rhapsody workspace

1. Choose File > Open. The Open window displays.

2. In the Look in field, browse to the location of the project, then select the .rpy file.

Alternatively, type the name of the project file in the File name field.

3. Select the Without Subunits check box. This prevents Rational Rhapsody from loading
any project units. All project units will be loaded as stubs.

4. Click Open. The project file opens with no units loaded. This empty project acts as a
starting point for you to create your workspace.

5. Add units to your workspace to customize it for your needs.

Adding units to a workspace

1. Select the unit in the browser.

2. Right-click the unit, then select Load Unit.

3. Select the unit in the browser.

4. Right-click the unit, then select Load Unit with Subunits.

Unloaded units
Units of your project that have not been loaded into your workspace are marked with the letter
“U.” This designation means that the unit is a stub unit, and was either excluded from the project
intentionally, or was not found when Rational Rhapsody attempted to load the unit.

262 User Guide

 Using workspaces

In diagrams, a “U” located at the destination end of a relation, dependency, or generalization

means that the target is an unresolved element. In this case, the originator of the relation,
dependency, or generalization is loaded, but the unresolved element has been either intentionally
or accidentally excluded from the project.

You can use the Advanced search and replace features to locate any unloaded units and load them.

Opening a project with workspace information

To open a workspace:

1. Select File > Open. The Open window displays.

2. In the Look in field, browse to the location of the project, then select the .rpy file.
Alternatively, type the name of the project file in the File name field.

3. Select the Restore Last Session check box. The project opens with the workspace
information that was saved during your last Rational Rhapsody session.

To open a project without loading workspace information, see Opening an existing Rational
Rhapsody project.

Controlling workspace window preferences

Workspaces save information about your window preferences. These preferences include window
size, position, status of feature windows, and the scaling or zoom factor of open diagrams.

To prevent Rational Rhapsody from saving graphic editor settings, set the
OpenDiagramWithLastPlacement property under General::Workspace BlockIsSavedUnit
check box to Cleared. With this setting, Rational Rhapsody does not save the position of graphic
editor windows. Instead, it uses the default window settings the next time you open a graphic
editor.

You can prevent Rational Rhapsody from saving any window preferences by setting the
OpenWindowsWhenLoadingProject property under General::Workspace check box to Cleared.

Rational Rhapsody 263

Rational Rhapsody projects

Project files and directories

The project directory is the top-level directory for a project. It is the folder entered in the New
Project window when you create a new project. Rational Rhapsody creates a number of project
files with matching directories. Each project file/directory pair shares the same name.

The following table lists project files created by Rational Rhapsody.

File Name Description

<Project>.rpy The project file or model repository. Requires the repository
files in the <Project>_rpy directory to be a complete
model.
<Project>_rpy Directory containing unit files for the project, including:
• Components (*.cmp)
• Packages (*.sbs)
• Classes (*.cls)
• Use case diagrams (*.ucd)
• Sequence diagrams (*.msc)
• Object model diagrams (*.omd)
• Component diagrams (*.ctd)
• Collaboration diagrams (*.clb)
• Deployment diagrams (*.dpd)
• Structure diagrams (*.std)
• Table of files contained in the project (filesTable.dat)
<Project>_auto.rpy A backup file of the model, created during autosave. This file
is written only if the <Project>.rpy has been modified
since it was last saved.
<Project>_auto_rpy Directory containing a backup of project files modified since
the last save. All autosave files are stored in flat mode. For
more information, see Saving packages in separate
directories.
<Project>_bak1.rpy A backup of the model, created when the project is first
saved. Requires the repository files in the
<Project>_bak1_rpy directory to be a complete model.
<Project>_bak1_rpy Directory containing a backup of the project files for the
<Project>_bak1.rpy repository. This folder can contain
the same types of files as the <Project>_rpy folder.
<Project>_bak2.rpy A backup of the model, created when the project is saved a
second time. Contains the most recent backup of the project.
Requires the repository files in the <Project>_bak2_rpy
directory to be a complete model.
<Project>_bak2_rpy Directory containing a backup of the project files for the
<Project>_bak2.rpy repository. This folder can contain
the same types of files as the <Project>_rpy folder.

264 User Guide

 Project files and directories

File Name Description

<Project>.rpw Workspace settings file. Preserves the workspace settings for
the project. For more information, see Using workspaces.
<Project>.ehl Events history list. Stores events and breakpoints during
animation.
<Project>.vba VBA project file. Contains VBA macros, modules, user forms,
and so on.
ReverseEngineering.log A log of reverse engineering activity containing messages
reported in the output window during reverse engineering.
<Project>_ATG Directory that holds any tests created using the Rational
Rhapsody Automatic Test Generation add-on (if you added
the product).
<Project>_RTC Directory that holds any tests created using the Rational
Rhapsody TestConductor™ add-on (if you added the
product).
load.log A log of when various repository files were loaded into
Rational Rhapsody, including any errors that might have
occurred during the loading and resolution phases.
store.log A log recording when the project was saved.
<Component> Directory for each component in the project. Organizes files
generated for each configuration in the component. Each
configuration is placed in a subdirectory that contains the
source and binary files for a build.

Rational Rhapsody 265

Rational Rhapsody projects

Parallel project development

Many companies use Rational Rhapsody to create large models developed by multiple users, who
are often working in parallel in distributed teams. These teams might use a source control tool or
configuration management (CM) software, such as Rational ClearCase, to archive project units,
but not all files might be loaded into CM during development.

Engineers in the team need to see the differences between an archived version of a unit and another
version of the same unit or a similar unit that might need to be merged. To accomplish these tasks,
they need to see the graphical differences between the two versions, as well as the differences in
the code. However, source control software does not support graphical comparisons.

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

Unit types
A Rational Rhapsody unit is any project or portion of a project that can be saved as a separate file.
These are some examples of Rational Rhapsody units with the file extensions for the unit types:

Class (.cls)
Package (.sbs)
Component (.cmp)
Project (.rpy)
Any Rational Rhapsody diagram

266 User Guide

 Parallel project development

DiffMerge tool functions

The DiffMerge tool can be operated inside and/or outside your CM software to access the units in
an archive. It can be launched from inside or outside Rational Rhapsody. It can compare two units
or two units with a base (original) unit.

The units being compared only need to be stored as separate files in directories and accessible
from the PC running the DiffMerge tool. In addition to the comparison and merge functions, this
tool provides these capabilities:

Graphical comparison of any type of Rational Rhapsody diagram

Consecutive walk-through of all of the differences in the units
Generate a Difference Report for a selected element including graphical elements
Print diagrams, a Difference Report, Merge Activity Log, and a Merge Report

Note
Many of the DiffMerge tool’s operations can be run from a command-line interface to
automate some of the tasks associated with software development (for example, to schedule
nightly builds).

Rational Rhapsody 267

Rational Rhapsody projects

Project migration and multi-language projects

When you run Rational Rhapsody, you select a specific language version of Rational Rhapsody.
This determines the language that is associated with your Rational Rhapsody projects.

You can, however, open Rational Rhapsody projects that were created with other language
versions of Rational Rhapsody.

In addition, Rational Rhapsody allows a single model to contain units that are associated with
different languages. A model can include units associated with C, C++, or Java. Code can then be
generated in the appropriate language for each unit.

Note
While project migration is a built-in feature of Rational Rhapsody, you can only have multi-
language projects if you possess the special license required for this feature.

Opening models from a different language version

Rational Rhapsody allows you to open models created in a different language version of Rational
Rhapsody. This is also referred to as migration of projects.

When you try to open a project that was created in a different language version of Rational
Rhapsody, you are notified that the project will be converted to the language of the current version,
and you are asked whether you would like to continue with the conversion of the project.

Note
When you migrate a project, you do not lose any language-specific features of model
elements that are not supported in the language version of Rational Rhapsody that you are
running. These language-specific characteristics will not be displayed, for example, in the
Features window, and any code generation will be in the language of the current version not
the version with which the model was originally created. However, Rational Rhapsody
maintains this information. If, at a later stage, you reopen the model in the original
language, you will once again see these language-specific characteristics.
When a project is migrated, bodies of operations and any other code entered manually in Rational
Rhapsody are not converted to the target language. If you already have such code in your model
before the migration, make sure to convert the code in order to avoid compilation errors.

If you use Add by reference to add a unit whose language differs from that of the version of
Rational Rhapsody you are running, a non-persistent conversion is performed (since these
elements are read-only). This non-persistent conversion will be performed each time you open the
model.

268 User Guide

 Project migration and multi-language projects

Note
If you have a license for multi-language projects, no conversion is performed when you
open a model from another language version of Rational Rhapsody. If you would like to
convert an entire project, just change the unit language at the project level. For details, see
Determining language of a unit in multi-language projects.

Multi-language projects
Rational Rhapsody uses units to permits projects to contain components from different
development languages. Each unit is associated with a specific language.

Determining language of a unit in multi-language projects

When you create a new unit, the Unit Information window provides a list that allows you to select
a specific language for the unit. The default language for a new unit is the language of its owner
unit.

To change the language of an existing unit:

1. Right-click the unit in the browser, and then select Unit > Edit Unit.

2. When the Unit Information window is displayed, select the language from the list.
3. Click OK.

4. When you are asked to confirm the change, click Yes.

If you are changing the language of a unit that contains subunits, Rational Rhapsody will ask you
if you also would like to change the language of all of the contained subunits.

Note
As is the case for project migration, if you change the language of a unit, you do not
permanently lose any language-specific features of the unit. These language-specific
characteristics will not be displayed, and any code generation will be in the new language.
However, Rational Rhapsody maintains this information. If, at a later stage, you switch the
unit back to the original language, you will once again see these language-specific
characteristics.
When you move units of one language to a package of another language, Rational Rhapsody will
inform you that they are different languages and will ask you to confirm the move.

If you try to add a unit that is associated with another language, Rational Rhapsody will ask you to
confirm the addition of the unit. You will also be prompted for confirmation if you add “by
reference” a unit that is associated with another language.

Rational Rhapsody 269

Rational Rhapsody projects

Code generation
In each of the language versions of Rational Rhapsody, you can generate code for units in each of
the three languages - C, C++, Java.

For code generation to work properly, you have to adhere to the following rules:

To generate code for units in a certain language, the appropriate language must be
specified at the component level.
Elements included in the scope of a component must be of the same language as the
component. (If other language elements are included in the scope, a warning will be
issued during code generation.)

Note
If you select All Elements as the scope, Rational Rhapsody will automatically include only
those units whose language matches that of the component. If you choose Selected
Elements, Rational Rhapsody will only display those units whose language matches that of
the component. However, if you selected specific elements, and then changed the language
of the component, Rational Rhapsody will not deselect these non-matching units. When you
attempt to generate code with such a component, you will receive error messages.
The same principle applies to the Initial Instances specified for the configuration.

Language-specific differences in Rational Rhapsody

The Features window differs from language to language. For each unit in your model, the
appropriate Features window is displayed.

Similarly, the properties displayed reflect the language of the selected unit.

Non-unit elements
If you try moving an element not saved as a unit to a package with a different language, the
language of the element will be changed to that of the receiving package after you confirm that you
want to move the element.

Reverse engineering
The reverse engineering mechanism always uses the language of the active component. When you
use the Reverse Engineering window to add files to reverse engineer, the default file filter used
will reflect the language of the active component, for example, *.java if the active component is
associated with Java.

270 User Guide

 Project migration and multi-language projects

Miscellaneous issues
Rational Rhapsody API: The interface IRPUnit allows recursive changing of unit
language.
ReporterPLUS can query the language of an element.
The Rational Rhapsody internal reporter shows the language of each saved unit.
XMI: Language of each unit is exported and imported.
Graphic Editor: Changes to language of a unit do not affect the depiction of the unit in the
graphic editor. For example, if you change the language of a template class to C, it will
still look like a template class in the graphic editor.
DiffMerge checks for language differences.
PredefinedTypes package: These packages are language-dependent. When you create a
unit whose language differs from that of the Rational Rhapsody version being used, the
relevant package of predefined types for that language will be loaded.

Rational Rhapsody 271

Rational Rhapsody projects

Domain-specific projects and the NetCentric profile

The Rational Rhapsody NetCentric Profile builds domain-specific projects for a Service Oriented
Architecture (SOA) or to support Network Centric Warfare (DoDAF) Applications. In SOA
projects, developers begin by writing the interface specifications using Web Service Description
Language (WSDL), a complex XML schema.

Unfortunately, WSDL requires that the data types be fully defined and contain legal XML types.
WSDL also requires the developers to define the interface calls in terms of where the services are
to be deployed (bindings and namespaces). These details are not always known during the initial
design phase. The Rational Rhapsody NetCentric profile helps the engineer bridge this gap from
the design concepts to the WSDL file production.

SOA or NetCentric application model roles

SOA and NetCentric application models have two roles:

Service provider or the service itself

Service consumer is the user of the service

Service consumers
A service consumer can be any actor, application, or any other receiver of the deployed service.
For example, a weather station might receive the weather information provided by a SOA
application.

Using the platform independent WSDL files for application output, service users gain access to the
output more easily than from output in a proprietary format.

Service provider
The service provider is the code that implements the service. The service provider includes the
interface specification (also called the service contract) and the related WSDL file. The service
provider also includes everything necessary to produce the WSDL file:

Service contract (interface class)

Realization of this contract (classes that implement the service)
Data types
WSDL file.

272 User Guide

 Domain-specific projects and the NetCentric profile

Rational Rhapsody uses the stereotype <<servicePackage>> to indicate a UML/SysML package

that contains the model elements necessary for creating the WSDL file that includes the package
with the service provider and the service contract. The stereotypes <<serviceProvider>> and
<<serviceContract>>, respectively, indicate these classes. To define the data types, the
WSDL files also include XML schemas and XSDs.
This Block Definition diagram example shows a typical collaboration in which the stereotypes
indicate the service contract, service consumer, and service provider.

Collaborations in a top level or System of Systems model allow the systems engineers to confirm
the data types, interfaces, and basic block behavior before generating the WSDL file. Executing
the model ensures that both sides of the interface interpret messages the same way. This avoids
consistency errors that, otherwise, might not be discovered until late in the integration phase.

Rational Rhapsody 273

Rational Rhapsody projects

The systems engineers and designers might model data types using the SysML units and value
types, as shown the Block Definition diagram example (from Rational Rhapsody System samples
“NetCentricWeatherService” project):

The Generate WSDL Specification tool uses these data types to create the schema information
within the WSDL file.

274 User Guide

 Domain-specific projects and the NetCentric profile

Creating a NetCentric project

The NetCentric profile is available as a standard profile selection in the following Rational
Rhapsody editions:

Developer edition for C, C++, Java, and Ada projects

Architect for Systems Engineers edition
Architect for Software edition
To create a NetCentric project from one of these editions:

1. With your Rational Rhapsody edition running, create the new project by either selecting
File > New, or clicking the New project button on the main toolbar.

2. Replace the default project name (Project) with <your project name> in the Project
name field. Enter a new directory name in the In folder field or Browse to find an
existing directory.

3. Select the NetCentric Project Type.

4. You might want to select a different option for the Project Settings.

5. Click OK. If the directory does not exist, Rational Rhapsody asks if you want to create it.
Click Yes to create the new project directory.

To add the NetCentric profile manually to an existing project:

1. With the Rational Rhapsody project open, choose File > Add Profile to Model.

2. In the Add to Profile Model window, select the Package (*.sbs) file for the NetCentric
profile. (If the NetCentric.sbs file is not displayed in the Profiles directory, the project
you have created is not compatible with the NetCentric profile. The SysML project profile
is often used with the NetCentric profile.)

3. Click Open to add the profile to your project.

Creating a service contract to export as WSDL

In order to create a service contract to export as a WSDL file, you must assign the set of
NetCentric stereotypes to the service package in your Rational Rhapsody project.

To create a service contract to export as WSDL:

1. In a Rational Rhapsody NetCentric project, define an interface block or class. This

interface contains the methods that define the service that is called by the service
consumer.

2. In the browser, right-click the interface block or class and select Features.

Rational Rhapsody 275

Rational Rhapsody projects

3. In the Stereotype field, select <<New>> and enter serviceContract. Click OK.

4. Create the block or class that realizes the serviceContract. Apply the stereotype
<<serviceProvider>> to it.

5. Add a standard port to the <<serviceProvider>>. Set the port to provide the service
contract interface. Stereotype this port <<servicePort>>.

6. Define all of the data types needed by the interface.

7. Set the stereotype on the package to <<servicePackage>>.

Exporting a WSDL specification file

To export a WSDL specification file from your Rational Rhapsody project:

1. Open the NetCentric project containing the WSDL specification. It is stored as a

<<wsdlDefinitionDocument>> stereotyped package.

2. Select that package in the project browser.

3. Select Tools > Generate WSDL Specification.

4. Enter the name and location for the output of WSDL specification file. Specify the target
output file with the .wsdl extension.
5. Click OK.

When the export is complete, you can open the WSDL file in any editor.

Importing a WSDL specification

To import a WSDL specification file into a Rational Rhapsody project:

1. With the Rational Rhapsody project open, choose Tools > Import WSDL Specification.

2. Select the previously generated WSDL file and click Open.

276 User Guide

 Schedulability, Performance, and Time (SPT) profile

Schedulability, Performance, and Time (SPT) profile

The SPT profile (also known as the UML Real-Time profile) is a standard UML profile adopted by
the OMG. The profile has the following uses:

Enable the construction of models that could be used to make quantitative predictions
regarding these characteristics.
Facilitate communication of design intent between developers in a standard way.
Enable interoperability between various analysis and design tools.
The SPT.rpy model provided in <Rational Rhapsody installation
path>\Share\Profiles\SPT is the Rational Rhapsody implementation of the standard profile that
you can use in any Rational Rhapsody model.

Note
This functionality can only be used with Rational Rhapsody in C++.

Manually adding the SPT profile to your model

If you have not created your project using the SPT profile as the Type, you can add the SPT profile
to your model:

1. Open your Rational Rhapsody model.

2. Choose File > Add Profile to Model.

3. On the Add Profile to Model window, select the SPT.sbs unit.

4. Click Open.

5. On the Add To Model From Another Report window, select the As reference radio button.
6. Click OK.

Rational Rhapsody adds the SPT profile as a reference profile to your model. As a result, the
stereotypes and tagged values of the profile become available.

Rational Rhapsody 277

Rational Rhapsody projects

Using the stereotypes and tagged values

1. Select the model element (for example, a class named MyClock).

2. Assign the stereotype you want to the model element (for example, RTclock).
3. Set tag values through the Tags tab of the Features window for the element.

Changing the profile

To change the profile, edit the SPT model.

Note
Deleting a stereotype or changing its metaclass might result in unresolved references in the
models using it (that is, the models that are referencing the SPT model and have elements
with this stereotype).

278 User Guide

 Rational Rhapsody with IDEs

Rational Rhapsody with IDEs

You can connect Rational Rhapsody to another development tool or IDE (integrated development
environments) to use features of both. You can use Rational Rhapsody with these IDEs:

Eclipse
Visual Studio
Tornado
Rational Rhapsody provides some standard menu commands to setup and work within both
environments.

IDE options
Use the Code > IDE Options on the Rational Rhapsody menu to set the ports to receive and send
messages for the IDE and Rational Rhapsody and synchronize the IDE with Rational Rhapsody.

Locating Rational Rhapsody elements in an IDE

If you want to locate an element from a Rational Rhapsody project in another development tool
(IDE), select the element in Rational Rhapsody and select Edit > Locate in IDE or press
Ctrl+Alt+K. The program, such as Eclipse or Visual Studio, opens and displays the element in its
project environment.

Opening the IDE

To work in the IDE, open Rational Rhapsody and choose Code > Open IDE. Your configured
IDE, such as Eclipse or Visual Studio, launches.

Creating an IDE project

After you have created a configuration for the IDE in your Rational Rhapsody project, you can
create a project in the IDE. Right-click the IDE configuration and select Create IDE Project.
Your configured IDE launches.

Rational Rhapsody 279

Rational Rhapsody projects

Using the Rational Rhapsody Workflow Integration

with Eclipse
The Rational Rhapsody plug-in for Eclipse has two implementations:

Rational Rhapsody Workflow Integration allows the software developer to work in

Rational Rhapsody and use some Eclipse features through Rational Rhapsody menu
commands. This integration can be used for C and C++ development in either Windows
or Linux environments. Both Eclipse and Rational Rhapsody must be open when the
developer is using this integration.
Rational Rhapsody Platform Integration permits developers to work on a Rational
Rhapsody project completely within Eclipse. Rational Rhapsody does not need to be open
for this implementation. This integration can be used for C, C++, or Java development in
a Windows environment only.
The Rational Rhapsody Workflow integration with Eclipse allows software developers to work on
Rational Rhapsody C or C++ projects in Eclipse version 3.3 or WindRiver’s Eclipse Workbench
2.6 to perform these tasks:

Create a new IDE (integrated development environment) configuration in Rational

Rhapsody in order to perform the following tasks:
– work in Eclipse on a new Rational Rhapsody project
– attach an existing Rational Rhapsody project to an existing Eclipse project
Import legacy Eclipse models into Rational Rhapsody UML models
Make changes in Eclipse and rebuild the project automatically in both Rational Rhapsody
and Eclipse
Use the debugging facilities in Rational Rhapsody and Eclipse in a synchronized manner
Use Rational Rhapsody reverse engineering with an active Eclipse configuration
Disconnect an Eclipse project from the associated Rational Rhapsody configuration

280 User Guide

 Using the Rational Rhapsody Workflow Integration with Eclipse

Converting a Rational Rhapsody configuration to Eclipse

If you created a configuration in Rational Rhapsody, but now you want to convert it into an Eclipse
configuration:

1. Open Rational Rhapsody and in the Rational Rhapsody browser, right-click the
configuration that you want to convert to be an Eclipse configuration and then select the
Change to > Eclipse Configuration.

2. From this point, the process is the same as creating a new Eclipse configuration.

Outline
Navigator

Importing Eclipse projects into Rational Rhapsody

Rational Rhapsody makes it easy for you to import your Eclipse projects quickly. When you
import an Eclipse project, all elements contained in the project are reverse engineered and added
as elements of a Rational Rhapsody model. The imported elements are added in a new package
which uses the name of the original Eclipse project. To import an Eclipse project:

1. Create a new Rational Rhapsody project, or open an existing Rational Rhapsody project.

2. Select Tools > Import from Eclipse.

3. If Eclipse is not currently open, Rational Rhapsody will launch it (after first asking you to
confirm that you want Eclipse opened), and the Export Rhapsody Model window will be
displayed in Eclipse. (If the window does not appear, check the port settings used; select
Code > IDE Options from the main Rational Rhapsody menu.)

4. Select the projects that you would like to export to Rational Rhapsody. (If an Eclipse
project has already been imported into Rational Rhapsody, it will not appear in the list of
available Eclipse projects.)

5. If you want the elements in the project to be added to the Rational Rhapsody model as
external elements, select Export as External.

6. If you want to fine-tune the reverse engineering options that will be used for importing
your Eclipse project, select Open Reverse Engineering options dialog in Rhapsody
before export.

7. Click Finish. All of the elements in the Eclipse project will be imported into the open
Rational Rhapsody project.

8. When the import process has been completed, look in the Rational Rhapsody browser for
a package that has the same name as the Eclipse project you imported. You will also

Rational Rhapsody 281

Rational Rhapsody projects

notice that a new component has been added to your Rational Rhapsody model,
containing an Eclipse configuration named after your Eclipse project.

Creating a new Eclipse configuration

If the developer or designer prefers to use the Eclipse IDE (integrated development environment)
to work on a project previously created in Rational Rhapsody:

1. Display the existing Rational Rhapsody C or C++ project in Rational Rhapsody.

2. In the Rational Rhapsody browser, right-click the Component in the Rational Rhapsody
project for which you want to create an Eclipse configuration and then select Add New >
Eclipse Configuration. The system displays a window, asking whether or not the user
wants to launch the IDE if it is not running.

Note: If IDE is already running, be certain that the ports for Eclipse and Rational
Rhapsody match by selecting the Code > IDE options from the Rational
Rhapsody menu and making any changes required. If the ports do not match, a
new IDE might open even if the user meant to switch to the running IDE!
3. For the WindRiver version of Eclipse, the Workspace Launcher displays so that you can
select a directory for your Eclipse project workspace. Click OK to save the selected
directory.
4. Then the Rhapsody Project Wizard displays. It lists the name of the Rational Rhapsody
project and the component you selected for the new Eclipse configuration. Select whether
you want to create a New Project or an Existing Project. Click Finish.

5. The New Project window displays Wizard types. However, currently only the vXWorks
Downloadable Kernel Module Project is supported. Select it and click Next.

6. Type a Project name and select a workspace in this window. Complete setting up the
Workbench project, as described in the Workbench documentation.
7. The Application Development interface displays the Eclipse configuration of the selected
Rational Rhapsody component.

8. Back in Rational Rhapsody, the browser now contains the new Eclipse configuration.

282 User Guide

 Using the Rational Rhapsody Workflow Integration with Eclipse

Troubleshooting your Eclipse installation with Rational Rhapsody

If after installing Eclipse, working to set up a project as described previously, and you have not
been successful, do the following troubleshooting to check your installation:

1. Check the path to Eclipse in the rhapsody.ini file to be certain that it is the actual path on
your system. The following example shows a typical path:
[IDE]
EclipsePath=C:\eclipse\eclipse.exe

Note: If it does not match your path to Eclipse, make the necessary changes.
2. Check to be certain that the c:\cygwin\bin is in your environment PATH variable.

3. Start Rational Rhapsody and create or open a project.

4. Right-click the component and choose Add New > Eclipse Configuration.

5. You are prompted for a workspace. Then the Rhapsody Project Wizard asks you to either
specify a project or create a new one. Click Next.

6. Specify the new project name and click Next.

7. Click Finish.

8. If the program asks if you want to associate with a C++ Perspective, click Yes. Now the
Eclipse CDT IDE is open and linked to your Rational Rhapsody project.

9. Switch to Rational Rhapsody and make sure your Eclipse configuration is active. Generate
code.

10. Right-click a model element in the Eclipse version of the code and select Locate in
Rhapsody. This change should trigger a roundtrip in the Rational Rhapsody version of
the code if the change is not one of the Workflow integration with Eclipse limitations.

Rational Rhapsody 283

Rational Rhapsody projects

Switching between Eclipse and Wind River Workbench

When Rational Rhapsody launches an Eclipse-based IDE, whether the generic Eclipse or Wind
River Workbench, it checks the rhapsody.ini file to determine the path of the IDE.

Then entry that stores this information is called EclipsePath and it is located in the section [IDE].
During installation, you will be asked to provide the path for Eclipse, and this information is
copied to the rhapsody.ini file, for example:
EclipsePath=l:\windriver\workbench-2.4\wrwb\2.4\x86-win32\bin\wrwb.exe
If you want to switch between the generic Eclipse and Wind River Workbench, change the value of
this entry in the rhapsody.ini file.

Rational Rhapsody tags for the Eclipse configuration

After creating an Eclipse configuration, the Rational Rhapsody model elements are coupled with
an Eclipse-based project. The definition of the Eclipse project is stored in Rational Rhapsody in
these Tags (displayed in the Rational Rhapsody browser):

IDEName is the name of the type of integrated development environment (for example,
Eclipse, Workbench).
IDEProject is the project name entered while creating the Eclipse configuration.
IDEWorkspace is the workspace directory for the Eclipse-based project.
The values of the tags are set automatically after the IDE project is created or mapped to the
configuration. You do not need to modify the values of these tags, unless you change the IDE
workspace location in the file system. If you make that change, then you must update the
IDEWorkspace tag manually. For instructions to make this change if necessary, see Configuring
Rational Rhapsody for Eclipse.

Configuring Rational Rhapsody for Eclipse

To examine the features of an Eclipse configuration in Rational Rhapsody:

1. Right-click the Eclipse configuration in the Rational Rhapsody browser.

2. Select Features from the menu to display this window. This version of the Features
window contains the IDE, Tags, Properties, and Settings tabs for use with Workbench
projects.
3. The IDE tab provides two important features:

Open in IDE launches Eclipse with the corresponding project or simply bring the
IDE forward.

284 User Guide

 Using the Rational Rhapsody Workflow Integration with Eclipse

Build configuration in IDE sets the build to be performed via the IDE (by
sending a request to the IDE)
4. However, if you want to perform the build in Rational Rhapsody, use the Settings tab to
make the build selections.

5. Generally, you do not need to change the values for the Tags, unless you change the
IDEWorkspace directory location. In that case, you must make the change to the path in
the window and click OK.

Eclipse workbench properties

To define the configuration and environment for the IDE project, the following Rational Rhapsody
properties are available in the Configuring Rational Rhapsody for Eclipse:

Subject Metaclass Property Name Default Value Description

Eclipse Configuration InvokeExecutable $executable Points to the executable.
Keywords:$executable - the
IDE executable as read from
Rhapsody.ini
Eclipse Configuration InvokeParameters -data $workspace Parameters for the command-
-vmargs - line.
DRhpClientPort=$ Keywords:
RhpClientPort -
DRhpServerPort=$ $workspace as specified in
RhpServerPort the Rational Rhapsody tags
for the Eclipse
configuration.
$RhpClientPort: the port
number that Rational
Rhapsody uses to be a
client to Eclipse, as
specified using Rational
Rhapsody menu Code >
IDE options.
$RhpServerPort: the port
number that Rational
Rhapsody uses to be a server
to Eclipse
Eclipse DefaultEnvironments Eclipse Cygwin The default environment in the
settings tab for generic Eclipse
(CDT) projects
Eclipse DefaultEnvironments Workbench WorkbenchManaged The default environment in the
settings tab for generic Eclipse
(CDT) projects

Rational Rhapsody 285

Rational Rhapsody projects

Editing Rational Rhapsody code using Eclipse

To edit code from Rational Rhapsody using Eclipse:

1. Open the Rational Rhapsody project that contains the Eclipse configuration and make it
the active configuration.

2. Launch Workbench.

3. In Rational Rhapsody, right-click a class and select Edit code in Eclipse from the menu.

4. The implementation of that class is then displayed in Eclipse, and Eclipse automatically
generates a file in DMCA mode in Rational Rhapsody.

5. Edit the code as needed. The updates are recorded in the implementation of the class.

Locating implementation code in Eclipse

If you want to examine the implementation code for model elements or errors using Eclipse:

1. Open the Rational Rhapsody project that contains the Eclipse configuration and make it
the active configuration.

2. Launch Workbench.
3. In Rational Rhapsody, right-click a model element, such as an attribute for a class in the
browser, and select Locate in Eclipse from the menu.

4. The implementation code displays in Eclipse.

Opening an existing Eclipse configuration

After creating Eclipse configurations for the Rational Rhapsody components that you want to
work on in Eclipse, to open Eclipse:

1. Start Rational Rhapsody.

2. Choose Code > IDE Open.

3. Eclipse launches. If the active configuration in the Rational Rhapsody browser is an

Eclipse configuration, that configuration is automatically displayed in Eclipse. If the
active configuration is not an Eclipse configuration, the system displays a window asking
the Eclipse workspace directory. Then it displays the Eclipse configuration in the
workbench interface.

Note: Only those elements that can be edited in Rational Rhapsody can be opened for
editing in Eclipse.

286 User Guide

 Using the Rational Rhapsody Workflow Integration with Eclipse

Disassociating an Eclipse project from Rational Rhapsody

To disassociate an Eclipse project from Rational Rhapsody:

1. In the list of C/C++ or Java projects in Eclipse, right-click the project and then select
Rhapsody > Disconnect from Rhapsody.

2. Click OK.

This removes the Rational Rhapsody characteristics from the project.

When you return to Rational Rhapsody, you are asked whether you want to delete the
corresponding Eclipse configuration from your model.

Note
In Rational Rhapsody, if you delete the Eclipse configuration from the model, the Eclipse
project will automatically be disconnected from the model.

Workflow integration with Eclipse limitations

When using the Rational Rhapsody workflow integration with eclipse, operations originating in
Rational Rhapsody and continuing into Eclipse cannot be undone. In addition, the $executable is
mapped to a single IDE. To work with several IDEs, the user must set the properties.

Rational Rhapsody 287

Rational Rhapsody projects

Visual Studio IDE with Rational Rhapsody

You can use Microsoft Visual Studio 2008 (standard or professional edition) with Rational
Rhapsody for C and C++ projects.

Changing an existing Rational Rhapsody configuration to Visual

Studio
To convert your Rational Rhapsody configuration into a Visual Studio configuration:

1. Open a Rational Rhapsody project.

2. Select the active Rational Rhapsody configuration in the browser.

3. Select Change to > Visual Studio Configuration.

Adding a new Visual Studio configuration

To add a Visual Studio configuration to your Rational Rhapsody project:

1. Open a Rational Rhapsody project.

2. Select the Rational Rhapsody configurations in the browser.

3. Select Add New > Visual Studio Configuration.

Creating a new Visual Studio project

After creating a Visual Studio configuration in Rational Rhapsody, you can perform the following
tasks:

work in Visual Studio on a new Rational Rhapsody project

attach an existing Rational Rhapsody project to an existing Visual Studio project
To create a new Visual Studio project, right-click the Visual Studio configuration and select
Create IDE Project.

288 User Guide

 Co-debugging with Tornado

Co-debugging with Tornado

Rational Rhapsody enables you to connect to the Tornado IDE, download an executable
component to the target, and perform source-code level debugging on the target while
simultaneously performing design-level debugging on the Rational Rhapsody host.

Integration of the Tornado IDE provides a seamless development workflow between Rational
Rhapsody and Tornado through the following functions:

Downloading and reloading an image directly to the target from Rational Rhapsody.
Synchronizing Rational Rhapsody breakpoints and Tornado breakpoints:
– Tornado (gdb) is aware of Rational Rhapsody-based breakpoints (break on
state).
– Rational Rhapsody is alerted for source-level breakpoints from Tornado.
This appendix provides information on the following topics:

Preparing the Tornado IDE

IDE operation in Rational Rhapsody

Co-debugging with the Tornado debugger

IDE properties

Preparing the Tornado IDE

To prepare the Tornado IDE for integration with Rational Rhapsody:

1. Open Tornado, then select Tools > TargetServer > (server name).
2. In Rational Rhapsody, make sure the active configuration is set to VxWorks.

Rational Rhapsody 289

Rational Rhapsody projects

IDE operation in Rational Rhapsody

Rational Rhapsody directly supports the following operations from the IDE submenu of the
Code > Target menu.

Code > Target > Connect opens a connection to the IDE server. In the case of Tornado,
this is the Tornado target server. This should be applied once during a session. The
connection is disconnected either explicitly or when the project is closed. To connect, you
must specify a target server name, typically <targetName>@<hostName>. Once specified,
the name is stored for future sessions.
Code > Target > Download downloads an image to the targets through the IDE.
Download is available only if an image exists.
Code > Target > Run. Runs the executable on the target starting from a designated entry
point (VxMain in Tornado), as specified by the
<lang>_CG::<Environment>::EntryPoint property. You can also run the executable
from the Code menu or toolbar.
Code > Target > Unload clears the target from all tasks and data allocated by the
application. This is an important feature because RTOSes generally do not have a process
concept that cleans up after termination of the application. Unload is always available and
causes execution to stop if the application is running.
Code > Target > Disconnect disconnects from the IDE server.

Co-debugging with the Tornado debugger

Before using the Tornado debugger, make sure to compile the generated file using debug flags
(normally -g).

To use the Tornado debugger:

1. In Rational Rhapsody, connect the application by selecting Code > IDE > Connect.

2. Download the application by selecting Code > IDE > Download.

3. Select Code > IDE > Run, or click Run.

4. In the Animation toolbar, select Go Idle (or Go Step several times) so the tRhp task is
created.

Note: You must run the application before attaching a debugger; otherwise, there will
be no tasks to which to attach the debugger.
5. In Tornado, start the debugger by selecting Tools > Debugger.

6. Attach the debugger to the main thread (tRhp) by selecting Debug > attach.

290 User Guide

 Co-debugging with Tornado

7. From the debugger, change directory to the generated code directory (using the cd
command in the gdb prompt).

8. From the debugger, load the symbols of the executable (using the add-symbol-file
command at the gdb prompt).
Now you can use gdb to debug the application, set breakpoints, and so on.

Before quitting animation on Rational Rhapsody, you must detach the debugger using Debug >
Detach. Failing to detach the debugger might block the session once Rational Rhapsody attempts
to unload the image.

Note
Do not download the executable to the target using the debugger. Rational Rhapsody will
not function properly if you use this method.

IDE properties
The following Rational Rhapsody properties (under <lang>_CG::<Environment>) determine IDE
settings:

HasIDEInterface

If this property is set to Cleared, no IDE services are attempted and IDE support is
disabled. If the property is Checked, it is expected that the IDEInterfaceDLL property
points to an IDE adapter that provides connection to the IDE. This property can be used to
disable the IDE connection. By default, it is set to Checked only for the VxWorks
environment.
IDEConnectParameters

This property specifies the IDE connection parameters. If this property is defined,
Rational Rhapsody will use the connection parameters from this property instead of the
.ini file.
IDEInterfaceDLL

This property points to the IDE adapter DLL. Currently, there is no reason to modify the
value of this property.

Rational Rhapsody 291

Rational Rhapsody projects

Creating Rational Rhapsody SDL blocks

Systems engineers often use the System Design Language (SDL) to model discrete (event driven)
algorithms. The SDL Suite also generates C code for its models. Rational Rhapsody in C++ is
integrated with the SDL Suite (version 5.0 or greater) to enable system simulation based on
Rational Rhapsody and the SDL Suite’s discrete behavior. Engineers can import an SDL model
into Rational Rhapsody. Rational Rhapsody manages the imported model as a class, stereotyped
with the SDLBlock.

Note
The naming convention for an SDL signal adds the “_” prefix to the signal’s original name.
This prefix can be modified by changing the SDLSignalPrefix property in the
Model::Profile group.

By default the SDLBlock uses behavioral ports. This configuration can be changed to use a rapid
port instead by selecting the UseRapidPorts property for the package. This property is also stored
in the Model::Profile group that you access from the Properties tab of the Features window.

Note
The SDL models you import into Rational Rhapsody cannot contain more than a single
instance of any given process.
To import an SDL model into Rational Rhapsody:

1. In the SDL Suite, open the SDL model. Mark the System level rectangle.

2. From the main menu select Generate > Make.

3. Select the CAdvanced Code Generator configuration.

4. Select the Generate environment header file check box.

5. Activate the “Make” to generate the model C file (modelname.c) and environment header
file (modelname.ifc).

6. Select SDLAccess Code Generator configuration and activate the Full Make to generate
the model SDL_Access file (modelname.sac).

7. Open Rational Rhapsody and choose File > New.

8. Select the SDL_Suite for the project Type.

9. Create a new block/class and select the SDLBlock class stereotype.

10. Right-click this block and select Import/Sync SDL Model.

292 User Guide

 Creating Rational Rhapsody SDL blocks

11. Enter the locations of the SDL model files you created previously, as shown in the
following example:

12. Click Import/Sync.

13. To connect the Rational Rhapsody block to an SDLBlock, create a user class with
behavior ports and a statechart. The statechart controls the user class’ sending and
receiving of events to and from the SDLBlock.

14. Create objects from the SDLBlock and the Rational Rhapsody block and connect their
ports via links using the interfaces that where created by the import.

15. To create an executable, perform a code generation and build on the entire Rational
Rhapsody model. Code generation scope should contain only one SDLBlock.

Note
Since the SDLBlock is imported as a “black box,” no animation is provided with this block.
There is an option to view the behavior of the SDLBlock as a wrapper via a sequence
diagram. This can be done by checking the AnimateSDLBlockBehavior property, located in
the Model::Profile property group.

Rational Rhapsody 293

Rational Rhapsody projects

294 User Guide

 Model elements

The Rational Rhapsody browser lists all the design elements in your model in a hierarchical,
expandable tree structure, enabling you to easily navigate to any object in the model and edit its
features and properties. The Rational Rhapsody browser also takes part in animation by displaying
the values of instances as they change in response to messages and events.

To help you manage large and complex Rational Rhapsody projects, and to be able to focus on and
easily access model elements of particular interest to you, you can filter the Rational Rhapsody
browser or create other browser views.

Browser techniques for project management

The Rational Rhapsody browser displays a list of project elements organized into folders. You can
choose to have all elements displayed in a single folder, regardless of their position in the model,
or have them displayed in subfolders based on the model hierarchy. The browser provides several
views so you can filter the display of elements by different design categories. The project is the
top-most folder in the Rational Rhapsody browser. It contains the following top-level folders:

Components, which contains one or more configurations and files

Packages, which contains actors, classes, events, globals, diagrams, types, use cases, and
other packages
Diagrams, which contains any of the UML diagrams that Rational Rhapsody supports
You can organize large projects into package hierarchies that can be viewed easily by nesting
packages, components, and diagrams inside other packages, and nesting classes and types inside
other classes.

Because a Rational Rhapsody project can get quite large and complex, you might want to filter
what you see on the Rational Rhapsody browser or otherwise create other browser views.

Rational Rhapsody 295

Model elements

Opening the Rational Rhapsody browser

By default, the Rational Rhapsody browser is displayed the first time you open a project. In
subsequent work sessions, Rational Rhapsody consults your workspace file (<project
name>.rpw) to determine whether to open the browser when it opens a project. For more
information on workspaces, see Controlling workspace window preferences.

To open the Rational Rhapsody browser manually, use any of the following methods”

Click the Show/Hide Browser button on the Rational Rhapsody Windows toolbar.
Select View > Browser.
Press Alt+0 (zero).

Browser display options

The browser has two display modes: Flat and Categories. In Flat mode, only the components,
packages, and diagrams within each package have separate categories. In Categories mode, all
elements are organized into categories based on their position in the project hierarchy. The default
display mode is Categories mode.

The display mode for the project is stored in the Browser::Settings::DisplayMode property.Set
the property to Meta-class for Categories mode or Flat for Flat mode.

Setting the Organize Tree mode to flat

To hide the categories in the browser:

1. Position the cursor in the Rational Rhapsody browser.

2. Choose View > Browser Display Options > Organize Tree > Flat.

Expanding a category while in Flat mode reveals a flat list of elements of all types included under
that category. For example, expanding a package category reveals a simple list of the elements
contained in the package, such as actors, classes, and events, arranged alphabetically by name.

Setting the Categories mode

In Categories mode, each metatype displays in its own category. Individual items, such as
components, diagrams, packages, classes, and actors, are displayed under the appropriate category.

1. Position the cursor in the Rational Rhapsody browser.

2. Choose View > Browser Display Options > Organize Tree > Categories.

296 User Guide

 Browser techniques for project management

Displaying model element labels

To display the labels defined for model elements (instead of their names), choose View > Browser
Display Options > Show Labels.

Showing the implementation arguments

To display the implementation arguments in the browser, choose View > Browser Display
Options > Show Implementation Argument.

Setting the project scope

You might want to divide the system into multiple components, so that each component represents
a physical subsystem. To select the model elements for each component:

1. In the Components project folder, right-click the component.

2. Select Features and the Scope tab

3. To select all of the elements in the component, click the All Elements radio button.

4. To select individual elements to be included in the component, click the Selected

Elements radio button and click the check boxes of the elements, as shown below.

If you select a check box for an element, all of the elements that it contains are included in the
component scope (for example, all of the classes in a package). If you want to be able to select sub-
elements individually, right-click the check box of the parent element.

Rational Rhapsody 297

Model elements

Showing the active component elements within the project scope

To show the active component elements in bold type in the browser:

1. Open the Features window. Choose File > Project Properties.

2. Navigate to the General::Model::HighlightElementsInActiveComponentScope

property and select the check box.

3. Click OK. The elements of the active component within the scope are shown in bold type,
as shown in the following figure:

298 User Guide

 Browser techniques for project management

Basic browser icons

The icons before elements listed in the Rational Rhapsody browser provide additional information
about the elements so that you can quickly identify items you want to access. The following table
summarizes the standard icons for the Rational Rhapsody browser, but not the icons exclusive to
the speciality profiles, such as DoDAF. See the sections describing special features for the browser
icons that are available.

Name (if
Icons Description
available)
Folder Used to group and organize project elements.

Folder that is a The square in the lower left corner indicates that this folder is a unit. For information,
unit see Using project units.
Folder of For more information, see Hyperlinks.
hyperlinks

Component A physical subsystem in the form of a library or executable program or other

software components such as scripts, command files, documents, or databases.

Component that The square in the lower left corner indicates that this component is a unit.
is a unit

Active Component that is a unit and is set as the active component with a red check. To
component be the active component, a component must be either an Executable or a Library
build type. For more information, see Active component.
Executable application or a library

Actor Represents an end user of the system, or an external component that sends
information to or receives information from the system. For more information, see
Actors.
Class Defines the attributes and behavior of objects. For more information, see Classes.

Class with a statechart

Class attributes

Class operations

File Indicates an imported file.

Part A component or artifact of a system.

Rational Rhapsody 299

Model elements

Name (if
Icons Description
available)
Event An asynchronous, one-way communication between two objects (such as two
classes). For more information, see Events and operations.

Use case Captures scenarios describing how the system could be used. For more information,
see Use cases.

SuperClass Marks a class that inherits from another class. For more information, see
Inheritance.

Dependency Notes the relationship of a dependent class to a model element or external system
that must provide something required by the dependent class. For more information,
see Dependencies.
Constraint Supplies information about model elements concerning requirements, invariants in a
text format.

Stereotype A type of modeling element that extends the semantics of the metamodel.
Stereotypes must be based on certain existing types or classes in the metamodel.
For more information, see Stereotypes.
Type A stereotype of class used to specify a domain of instances (objects) together with
the operations applicable to the objects. A type cannot contain any methods. For
more information, see Types.
State An abstraction of the mode in which the object finds itself. It is a condition or situation
during the life of an object during which it satisfies some condition, performs some
activity, or waits for some event. For more information, see States.
Initial Marks the default state of an object. For more information, see Transitions.
Connector

Controlled file Files produced in other programs, such as Word or Excel, that are added to a project
for reference purposes and then controlled through Rational Rhapsody. For more
information, see Controlled files.
Association Defines a semantic relationship between two or more classifiers that specify
connections among their instances. It represents a set of connections between the
objects (or users). For more information, see Creating associations.
Flow port Represents the flow of data between blocks in an object model diagram (OMD)
without defining events and operations. Flowports can be added to blocks and
classes in object model diagrams.
Profile Applies domain-specific tags and stereotypes to all packages available in the
workspace. For more information, see Profiles.

Requirement Is a wanted feature, property, or behavior of a system. Requirements can be

imported or created in Rational Rhapsody.

Requirement verification

Tags Adds information to certain kinds of elements to reflect characteristics of the specific
domain or platform for the modeled system. For more information, see Use tags to
add element information.

300 User Guide

 Browser techniques for project management

Name (if
Icons Description
available)
Flow item

Comments Marks text added to a model element.

Table layout Shows the design for a table view of project data.
For more information, see Table and matrix views of data.
Table view Displays project data in the predefined table layout.

Matrix layout Shows the design for a matrix view of project data.

Matrix view Displays project data in the predefined matrix layout.

Activity diagram Shows the lifetime behavior of an object, or the procedure that is executed by an
operation in terms of a process flow, rather than as a set of reactions to incoming
events. For more information, see Activity diagrams.
Collaboration Displays objects, their messages, and their relationships in a particular scenario or
diagram use case. This diagram is also a unit. For more information, see Collaboration
diagrams.
Component Specifies the files and folders that components contain and defines the relations
diagram between these elements. For more information, see Component diagrams.

Deployment Shows the configuration of run-time processing elements and the software
diagram component instances that reside on them. For more information, see Deployment
diagrams.
Object model Shows the static structure of a system: the objects in the system and their
diagram associations and operations, and the relationships between classes and any
constraints on those relationships. For more information, see Object model
diagrams.
Requirements Shows requirements imported from other software products or created in Rational
diagram Rhapsody and illustrate the relationships between requirements and system
artifacts. For more information, see Creating Rational Rhapsody requirements
diagrams.
Sequence Describes message exchanges within your project. For more information, see
diagram Sequence diagrams.

Statechart Defines the behavior of objects by specifying how they react to events or operations.
For more information, see Statecharts.
Structure Models the structure of a composite class; any class or object that has an object
diagram model diagram can have a structure diagram. For more information, see Structure
diagrams.
Use case Illustrates scenarios (use cases) and the actors that interact with them. The icon in
diagram this example indicates that this use case diagram is also a unit. For more
information, see Use case diagrams.

Rational Rhapsody 301

Model elements

Rational Rhapsody browser menu options

The large size and nested hierarchy of a Rational Rhapsody project might complicate the process
of locating and working with model elements. To help you navigate the Rational Rhapsody
browser more easily, the browser has a filtering mechanism that you can use to display only the
elements relevant to your current task.

To display the filter menu, click the down arrow button at the top of the browser. Whatever view
you have selected is reflected in the label to the left of the arrow button.

Select one of these views:

Note
If the browser is filtered, you can add only elements that appear in the current view.
Entire Model View is the default view and it does not use a filter. It displays all model
elements in the browser.
Use Case View displays use cases, actors, sequence diagrams, use case diagrams, and
relations among use cases and actors.
Component View displays components, nodes, packages that contain components or
nodes, files, folders, configurations, component diagrams, and deployment diagrams.
This view helps you manage different components within your project and assists with
deploying them.
Diagram View filters out all elements except diagrams. It displays all the diagrams,
including statecharts and activity diagrams.
Unit View displays all the elements that are also units. This view assists with
configuration management. For information on creating and working with units, see
Using project units.
Loaded Units View displays only the units that have not been loaded into your
workspace. For more information, see Loading and unloading units and Unloaded units.
Requirement View displays only those elements with requirements.
Overridden Properties View displays only those elements with overridden properties.
To learn about other browser views, see The Browse From Here browser and The Favorites browser.

302 User Guide

 Browser techniques for project management

Deleting items from the Rational Rhapsody browser

You can delete items from your project through the main Rational Rhapsody browser and the
Browse From Here browser (see The Browse From Here browser).

To delete an item from your project:

1. Select the items in the main Rational Rhapsody browser or the Browse From Here
browser.

2. Right-click and select Delete from Model or choose Edit > Delete from the main menu.

The system asks for confirmation of the deletion operation.

3. Click OK.

Note
Delete from Model is not available for the Favorites browser (see The Favorites browser).
You can select one or more items and choose Edit > Delete from the main menu to delete
items from the Favorites browser (which is the same if you right-click and select Remove
from Favorites from the pop-up menu). However, this only means that you are removing
items from the Favorites browser. You cannot delete any model elements through the use of
the Favorites browser.

Rational Rhapsody 303

Model elements

The Browse From Here browser

Rational Rhapsody projects can become very large and complex, making it difficult to find
commonly used model elements in the Rational Rhapsody browser. To help limit the scope of the
current view of the browser, you can open a Browse From Here browser that contains the view of
the browser that you want. The Browse From Here browser is similar to the main Rational
Rhapsody browser except that it typically shows a more focused area of the main Rational
Rhapsody browser.

The Browse From Here browser operate in the same manner as the main Rational Rhapsody
browser, and it has the same look-and-feel. You can drag-and-drop between the main Rational
Rhapsody browser and one or more Browse From Here browsers.

The one feature that a Browse From Here browser has that the main Rational Rhapsody browser

does not is the Up One Level button .

For another method to help you view and access only those model elements you are most
interested in, see Rational Rhapsody browser menu options and The Favorites browser. Note that
you can have the main Rational Rhapsody browser, the Favorites browser, and one or more
Browse From Here browser open at any time.

Opening a Browse From Here browser

Note that you can open multiple Browse From Here browsers.

To open a Browse From Here browser, right-click a model element in the main Rational Rhapsody
browser, the Favorites browser, on a diagram, or another Browse From Here browser and select
Browse from here.

Note
Browse From Here is not available for elements inside sequence diagrams and
collaboration diagrams that are view-only elements.

Closing a Browse From Here browser

To close a Browse From Here browser, click the Close button for that browser.

Note that View > Browser is only for the main Rational Rhapsody browser.

304 User Guide

 The Browse From Here browser

Navigating a Browse From Here browser

You navigate a Browse From Here Browser as you would the main Rational Rhapsody browser.

To set the root to the parent of the current root, click the Up One Level button . Note that, if
you want, you can click this button as many times as needed to go to the project root folder (so that
your Browse From Here Browser ends up looking exactly like your main Rational Rhapsody
browser).

Deleting items from the Browse From Here browser

Just like the main Rational Rhapsody browser, you can delete items from your project through the
Browse From Here browser. See Deleting items from the Rational Rhapsody browser.

Browse From Here browser limitations

Browse From Here browsers are not saved when you close your project. Meaning that they will
not be opened or available when you open your project the next time.

Rational Rhapsody 305

Model elements

The Favorites browser

You can use the Favorites browser to create a favorites list, which is a list of items (model
elements) that you are most interested in for the opened Rational Rhapsody model. This is
analogous to the favorites functionality for a Web browser. You might find the Favorites browser
most useful with Rational Rhapsody models that are very large, which can make it difficult to find
commonly used model elements in the Rational Rhapsody browser. The Favorites browser should
help you manage large and complex projects by making it easier to focus on and easily access
model elements of particular interest to you.

The following figure shows a sample Favorites browser:

Note
The Favorites browser is available only for the stand-alone version of Rational Rhapsody
While the Favorites browser resembles the Rational Rhapsody browser and has some of its
functionality (for example, double-clicking an item on the Favorites browser opens the applicable
Features window, the view is refreshed when an item is renamed, it can be docked and undocked,
and so on), the Favorites browser has limited functionality (for example, there is no filtering
mechanism, certain commands, such as Cut, Copy, Paste, Add New, and Unit are not available,
and while you can remove items from the Favorites browser, you cannot use it to delete a model
element from your model).

Note
You cannot use the Favorites browser as a replacement for the Rational Rhapsody browser.

306 User Guide

 The Favorites browser

Your favorites list is saved in the <projectname>.rpw file, while the visibility and position of the
Favorites browser are saved in the Rhapsody.ini file, so that when you open the project the next
time, your settings will automatically be in place. When multiple projects are loaded, the Favorites
browser shows the favorites list for the active project.

Favorites toolbar
The Favorites toolbar provides tools for the Favorites browser. To display or hide this toolbar,
choose View > Toolbars > Favorites.

The Favorites toolbar includes the following tools:

Tool
Name Description
Button
Show/Hide Toggles between showing and hiding the Favorites browser.
Favorites

Add to Select a model element and then click this button to add what you selected to your
Favorites Favorites browser.

Showing and hiding the Favorites browser

To show the Favorites browser, use any of the following methods:

Click the Show/Hide Favorites button on the Favorites toolbar. The button acts as an
on/off toggle.
Select View > Favorites. This menu command acts as an on/off toggle.
Add an item to your favorites list. This automatically opens the Favorites browser. See
Creating your Favorites list.
To hide the Favorites browser, use any of the following methods:

Click the Close button for the browser.

Click the Show/Hide Favorites button on the Favorites toolbar.

Select View > Favorites.

Rational Rhapsody 307

Model elements

Creating your Favorites list

The Favorites browser automatically opens when you add an item to it.

To create your favorites list, use any of the following methods:

Select a model element in the Rational Rhapsody browser, the Browse From Here
browser, or on a diagram and click the Add to Favorites button on the Favorites
toolbar. (This toolbar should display by default. If it does not, choose View > Toolbars >
Favorites).
Right-click a model element in the Rational Rhapsody browser or on a diagram and select
Navigate > Add to Favorites.
Select a model element in the Rational Rhapsody browser, the Browse From Here
browser, or on a diagram and press Ctrl+d.

With the Favorites browser open, click the Add to Favorites button and then select
one or more items to add from the Select Items to Add to Favorites window. Note that
with this method, if you have a folder structure for your favorites list, you can specify
where to put a new favorite by selecting that folder (or the root node, Favorites) first in
the Favorites browser. Otherwise, your favorite is added to below the non-folder item you
have highlighted on the Favorites browser. See Creating a folder structure for your
Favorites.

308 User Guide

 The Favorites browser

With the Favorites browser open, right-click the root node (Favorites) or a folder and
choose Select Item to Add. See Creating a folder structure for your Favorites.
Click a model element on the Rational Rhapsody browser, the Browse From Here browser,
or on a diagram and drag it onto the Favorites browser. You can drop the dragged item
anywhere on the Favorites browser. See Re-ordering the items on your Favorites list.

Note
You cannot put a model element on your favorites list more than once. For example, if you
have ElementA in FolderA and you add ElementA to FolderB, the element is removed from
FolderA so that it can reside in FolderB. See Creating a folder structure for your Favorites.
In addition, Add to Favorites is not available for elements inside sequence diagrams and
collaboration diagrams that are view-only elements.

Creating a folder structure for your Favorites

You can have a flat file structure for your favorites or you can have a hierarchical folder structure.

To create a folder structure for your favorites list:

1. Open the Favorites browser (see Showing and hiding the Favorites browser).

2. Wherever you want to add a folder, click the New Folder button or right-click an item
on the Favorites browser and select Add New Folder. At this time, you can name your
folder.

3. Once you have added an item (at any level), you can add a subfolder for that item if you
want.

Rational Rhapsody 309

Model elements

Re-ordering the items on your Favorites list

To re-order the items on your favorites list, use any of the following methods:

Select an item on your favorites list and click the Move Up or Move Down buttons
on the Favorites browser.
Note: This method is not available for folders.
Right-click an item on your favorites list and select Move Up In Favorites or Move
Down in Favorites.
Note: This method is not available for folders.
Select one or more items on your favorites list and drag it to where you want to drop it. An
insertion line displays to indicate where you can drop it.

To drop an item into an empty folder or the root node (Favorites), move your pointer over
the folder so that it becomes highlighted and then drop your item.

310 User Guide

 The Favorites browser

Removing items from your Favorites list

When you remove items from your favorites list, you are only removing them from the Favorites
browser. You are not deleting them from your model.

Note
The item is removed once you execute the action. If you change your mind, you can add the
item to your favorites list again (see Creating your Favorites list).
To remove items from your favorites list, select one or more items on the Favorites browser and
then use any of the following methods:

Click the Delete Favorites button on the Favorites browser.

Press the Delete key.
Right-click and select Remove from Favorites.
Choose Edit > Delete.
If there are items in a folder to be removed, the system informs you of this and ask if you want to
remove the folder (and its items).

Rational Rhapsody 311

Model elements

Favorites browser limitations

Note the following limitations for the Favorites browser:

You cannot give a name that is different from the referenced element to a favorite (like you
can for a hyperlink or a favorite in a regular Web browser).
Since you can put different model elements with the same name on your favorites list,
there is a chance for confusion. To try to avoid this, notice the icon to the left of the model
element name. The icons provide you with a clue as to what type of model item you have
on your favorites list.

312 User Guide

 Elements

Elements
Primary model elements within the browser are packages, classes, OMDs, associations,
dependencies, operations, variables, events, event receptions, triggered operations, constructors,
destructors, and types. Primary model elements in OMDs are packages, classes, associations
(links), dependencies, and actors.

Rational Rhapsody in C and C++ classes and their instances are replaced by C equivalent object
types and objects, respectively. Similarly, class constructors and destructors are replaced by
initializers and cleanup operations.

Adding elements
In the browser, you can add new elements to the model either from the Edit menu or from the
pop-up menu. The location you select in the browser hierarchy determines which model elements
you can add. The new element is added in the scope of the current selection.

Select the project folder or a package, then select Edit > Add New > Component.
Right-click the project folder or a package and then select Add New > Component.

Note
If the browser is filtered, you can add only elements that appear in the current view.
When you add a new association end, a window opens so you can select the related model element.

1. Right-click the actor and then select Add New > Association End. The Add Association/
Aggregation window opens.

2. From the list, select the actor (or class) with which the current actor needs to
communicate.

3. Click OK.

When you create a new element, Rational Rhapsody gives it a default name. You can edit the name
of your new element by typing a new name directly in name field in the browser, or by opening the
Features window and entering a new name in the Name field.

Rational Rhapsody 313

Model elements

Naming new elements in the browser

To change the automatically generated name of a new element:

1. Click the new element in the browser to open the name for editing.

2. Type the element name that you want to use.

You can also select one of these options for the menu that is available when you are renaming an
element:

Right to left Reading order

Show Unicode control characters
Insert Unicode control character (for example, LRM - Left-to-right mark or RLM - Right-
to-left mark are available in a selection list)

Browser settings
When you open an existing project in a newer version of Rational Rhapsody, the system adds a
compatibility profile in the Settings folder, as shown in this example.

For more information about the Settings folder and profiles, see Profiles.

314 User Guide

 Components

Components
A component is a physical subsystem in the form of a library or executable program. It plays an
important role in the modeling of large systems that contain several libraries and executables. For
example, the Rational Rhapsody application has several dozen components including the graphic
editors, browser, code generator, and animator, all provided in the form of a library.

A component contains configurations and files. In the Rational Rhapsody hierarchy, a component
can be saved at the project level, or grouped within a package.

For instructions on editing components, see Component diagrams.

Configurations
A configuration specifies how the component is to be produced. For example, the configuration
determines whether to compile a debug or non-debug version of the subsystem, whether it should
be in the environment of the host or the target (for example, Windows versus VxWorks), and so on.
For more information, see Component diagrams.

Configuration files
Configurations manifest themselves as files. The ability to map logical elements to files enables
you to better specify implementations for code generation, and to capture existing
implementations during reverse engineering. Just as it might be desirable to map several classes
into a single package, so might it be desirable to map one or more packages into a single
subsystem. You control where to generate the source files for the classes (or packages) in a given
subsystem, either into a single directory or separate directories.

Which logical elements, or classes, to map into which files

The order of the classes in the file
Verbatim code chunks, such as macros and #define statements, that should be included
in generated source files
Whether to map each class to its own specification and implementation files, or to map
multiple classes to the same files
Whether specification and implementation files generated for a class, or set of classes,
have the same name or different names
Dependencies between classes
File scope definitions for user-defined code
For more information on files, see Component diagrams.

Rational Rhapsody 315

Model elements

Packages
A Rational Rhapsody project contains at least one package. Packages divide the system into
functional domains, or subsystems, which can consist of objects, object types, functions, variables,
and other logical artifacts. Packages do not have direct responsibilities or behavior; they are
simply containers for other objects. They can be organized into hierarchies, providing the system
under development with a high level of partitioning. When you create a new model, it will always
include a default package, called “Default,” where model elements are saved unless you specify a
different package.

These elements are described in detail in subsequent sections.

Classes (C++/J) Collaboration diagrams

Comments Sequence diagrams
Constraints Structure diagrams
Dependencies Object model diagrams
Flow charts Statecharts
FlowItems Tags
Flows Stereotypes
Functions (C/C++) Events
Hyperlinks Component diagrams
Object _types (C) Activity diagrams
Objects Actors
Packages Deployment diagrams
Receptions Files
Requirements Use case diagrams
Types (C/C++) Nodes
Variables Use cases

Package design guidelines

Packages provide a way to group large systems into smaller, more manageable subsystems.
Packages are primarily a means to group classes together into high-level units, but they can also
contain diagrams and other packages.

When creating packages, follow these basic guidelines:

Do not allow packages to become unmanageably large. Break them into subpackages.
Limit dependencies across packages. One way to do this is to use interfaces in their own
packages.

316 User Guide

 Packages

Creating a package
To create a package:

1. Right-click the project or the package category, then select Add New > Package.

2. Edit the name of the package using the package label in the browser.

3. Double-click the new package to open the Features window.

4. Select a stereotype for the package (if necessary) from the Stereotype list.

5. Select an object model or use case diagram as the main diagram for a package from the
Main Diagram list.

6. Enter a description for the package in the Description box.

In the generated code, this text becomes a comment located after the #define statements
and before the #include statements at the top of the .h file for the package.

Rational Rhapsody 317

Model elements

Using functions
The Functions category lists global functions, which are visible to all classes in the same package.

Creating a global function

1. Right-click the name of a package or the Functions category in the browser.

2. Select Add New > Function. A new function displays under the Functions category of the
selected package.

3. Edit the name of the new function in the browser.

Changing what a function returns

When a function returns an «existing type», it is returned by type pointer. You can set if the
function returns by "value"(), by "pointer"(*) or by "reference"(&).

To change what a function returns:

1. Right-click the function/operation and choose Features to open the Features window.

2. On the Properties tab, find the CPP_CG::Type::ReturnType property.

3. Change the value to any of the following choices:

– $Type* to return by "pointer"(*)

– $Type to return by "value"()
– $Type& to return by "reference"(&)
4. Click OK.

Using objects
Objects are instances of classes in the model and can be used by any class. They are typically
created in OMDs, but can be added from the browser. For instructions on creating an object in an
OMD, see Object model diagrams.

To create an object

1. Right-click the name of a package or the Objects category in the browser.

2. Select Add New > Object. The new object is displayed in the browser with the default
name object_n.
3. Optionally, rename the new object.

318 User Guide

 Packages

Using variables
Global variables are visible to all classes in the same package.

Note
Exercise caution when using global variables. If a global variable is used for a counter in a
shared library and multiple threads or processes can access the counter, inaccurate results
might occur if the global counter is not protected by a mutex or semaphore.

Creating a variable
1. Right-click the name of a package or the Variables category in the browser.

2. Select Add New > Variable.

The new global variable is displayed in the Variables category.

Variable ordering in C++

Consider the case where your model has variables defined directly in a package. These variables
define various constants (such as PI and DEGREES_PER_RADIAN). Some of these variables are
defined in terms of others, such that the dependent variable must be declared before the others for
the application to compile. However, Rational Rhapsody will not allow you to override the default
alphabetical order of the variable declarations.

There are at least two ways to solve this problem:

Define your constants using types. For example, assume a type named PI with the
following declaration:
const double %s = 3.14
In this syntax, the %s is replaced with the name PI.
A DEGREES_PER_RADIAN type would have the following declaration:
const double %s = 180.0 / PI
In this syntax, the %s is replaced with the name DEGREES_PER_RADIAN.

Because Rational Rhapsody allows you to change the order of the type declarations
such that PI is generated first, the compilation is successful.

Create a variable called PI of type const double with an initial value of 3.14. Create a
second variable called DEGREES_PER_RADIAN of type const double with an initial value
of 180.0 / PI. This will not compile because Rational Rhapsody generates the
DEGREES_PER_RADIAN variable before the PI variable.

On the DEGREES_PER_RADIAN variable, set the

CPP_CG::Attribute::VariableInitializationFile property to Implementation to

Rational Rhapsody 319

Model elements

initialize the variable in the implementation file. The default setting (Default) causes the
initialization to be put in the specification file if the type declaration begins with const;
otherwise, it is placed in the implementation file.

Now, your application will compile correctly.

Dependencies
Dependencies are relations in which one class (the dependent) requires something provided by
another (the provider). Rational Rhapsody supports the full dependency concept as defined in the
UML. Dependencies can exist between any two elements that can be displayed in the browser.
Dependencies can be created in diagrams or in the browser.

Constraints
UML constraints provide information about model elements concerning requirements, invariants,
and so on. Rational Rhapsody captures them in text format. For more information, see Annotations
for diagrams.

Classes
Classes define the attributes and behavior of objects. Classes can also be created in the object
model or collaboration diagram editors. For more information, see Creating classes.

Types
The Types category displays user-defined, rather than predefined, data types. Rational Rhapsody
enables you to create types that are modeled using structural features instead of verbatim,
language-specific text.

Receptions
A reception specifies the ability of a given class to react to a certain event (called a signal in the
UML). Receptions are inherited. If you give a trigger to a transition with a reception name that
does not exist in the class but that exists in the base class, a new reception is not created.

Events
An event is an asynchronous, one-way communication between two objects (such as two classes).
Events inherit from the OMEvent abstract class, which is defined in the Rational Rhapsody
framework. Events can be created in sequence diagrams, collaboration diagrams, statecharts, or
the browser.

320 User Guide

 Packages

Actors
An actor represents an end user of the system, or an external component that sends information to
or receives information from the system. Actors can be created in UCDs, OMDs, collaboration
diagrams, and the browser.

Use cases
A use case captures scenarios describing how the system could be used. It usually represents this
scenario at a high conceptual level. Use cases can also be created in the use case diagram editor.

Nodes
A node represents a computer or other computational resource used in the deployment of your
application. For example, a node can represent a type of CPU. Nodes store and execute the run-
time components of your application. In the model, a node can belong only to a package, not to
another node (that is, nodes cannot be nested inside other nodes).

Files
A file is a graphical representation of a specification (.h) or implementation (.c) source file. This
new model element enables you to use functional modeling and take advantage of the capabilities
of Rational Rhapsody (modeling, execution, code generation, and reverse engineering), without
radically changing the existing files. For more information, see Configuration files.

Rational Rhapsody 321

Model elements

Diagrams
A project has separate categories in the browser for object model, sequence, use case, component,
deployment, structure, and collaboration diagrams. Additionally, all of these diagrams (except
collaboration diagrams) can be grouped under a package.

Note: Statecharts and activity diagrams are displayed within the class they describe.
To add new statecharts and activity diagrams, select the class name in the
browser instead of the package.

Adding diagrams
To add a new diagram to an existing package:

1. Right-click the package in the browser.

2. Select Add New > Package.

3. Type the name of the new package in the highlighted area in the browser.

4. Right-click the new package and select the Add New > Diagrams submenu.
5. Select the type of diagram you would like to add. The New Diagram window opens.

6. Type a name for the new diagram in the Name field.

7. If you want to populate the new diagram automatically with existing model elements.
Click the Populate Diagram check box.

8. Click OK. If you selected Populate Diagram, another window displays to allowing you
to select which model elements to add to the diagram. Rational Rhapsody automatically
lays out the elements in an orderly and easily comprehensible manner.

9. The new diagram displays in the drawing area of the Rational Rhapsody window.

322 User Guide

 Diagrams

Locating an element on a diagrams

You can use the Rational Rhapsody browser and any code view window to quickly locate an
element on a diagram by using Locate On Diagram from the pop-up menu.

To use the Rational Rhapsody browser to locate an element on a diagram:

Note: These steps are the same from any code view window, except that you would
select the element from the code. For an example, see Example of Locate On
Diagram from code view.

1. Right-click an element in the Rational Rhapsody browser and select Locate On Diagram.

2. Notice that Rational Rhapsody opens a diagram in which the element (Elevator) is
displayed.

Note: If no diagram exists, a No Diagram Found message displays instead.

Rational Rhapsody 323

Model elements

Example of Locate On Diagram from code view

The following figure shows an example of selecting Locate On Diagram from a code view (as
shown in the lower half of the figure) and the diagram it found (as shown in the upper half of the
figure).

Note: The theBuilding element in the code view half of the following figure is
selected for illustrative purposes. You can place your cursor within the letters
of the element name or that particular line of code and right-click to select
Locate On Diagram.

324 User Guide

 Diagrams

Locate On Diagram rules

Locate On Diagram uses the following rules to determine what to open, in order of priority:

1. Open the main diagram of the element if the main diagram is set and does show the
element (as illustrated in the previous figure).

2. For an object, show the main diagram of its class if the main diagram is set and does show
the object.

3. Show a randomly chosen diagram that shows the element.

4. Look for its container only if it does not find the element on the diagram. For example, if
you try to locate an operation, Rational Rhapsody looks for a diagram that shows the class
for the operation.

Locate On Diagram limitations

The ability to use Locate On Diagram from the code view is based on the annotations in the code.
If the code is not annotated, Locate On Diagram will not be able to find the diagram. Note also in
this case that it will not display a No Diagram Found message.

Rational Rhapsody 325

Model elements

Element identification and paths

Packages and classes serve as containers for primary element definitions, in other words, recursive
composites or namespaces. Each primary model element is uniquely identified by a path in the
following format:
<ns1>::<ns2>::...::<nsn>::<name>

In this format, <ns> can be either a package or a class. Primary model elements are packages,
classes, types, and diagrams. Names of nested elements are displayed in combo boxes in the
following format:
<name> in <ns1>::<ns2>::...<nsn>

You can enter names of nested elements in combo boxes in the following format:
<ns1>::<ns2::<name>

326 User Guide

 Descriptive labels for elements

Descriptive labels for elements

Element naming conventions often result in complicated and difficult-to-use names for elements,
especially in large projects developed by many different individuals. For that reason, Rational
Rhapsody enables you to assign a descriptive label to an element. A label that does not have any
meaning in terms of generated code, but enables you to easily reference and locate elements in
diagrams and windows. A label can have any value and does not need to be unique, making it
possible for you to use non-English labels, reuse labels, and use labels that include spaces on
Solaris systems.

Once you have assigned a label, Rational Rhapsody uses it in place of the element name in
diagrams and dialogs by default. Reports display both the element name and the element label.

Note
The General::Graphics::ShowLabels property controls whether labels are displayed in
diagrams and dialogs.

Setting properties for Asian languages

The element labels support Asian language text in Chinese, Korean, Taiwanese, and Japanese. The
text input can be through the Features window, browser, or graphic editor, and all non-ASCII
characters are stored as RTF instead of plain text.

To set the project properties to use an Asian language font for text input:

1. Right-click on the project name in the browser and select Features.

2. Select the Properties tab.

3. From the View menu, select Filter and search property names for “font.”

4. Right-click on the font name and description that needs to be changed and click the
browse button to display the Font window.

5. Check to be certain that the font supports the Asian language you want to display. If the
font does not support the required character set, select a new font from the Font list, such
as MS Gothic that supports Kanji characters required for Japanese.

Rational Rhapsody 327

Model elements

6. Also in the Font window, check the Script selection and use the pull-down menu to select
the correct language, as shown in this example.

7. Click OK save the change. Make this same change to any other font properties that are
required.

328 User Guide

 Descriptive labels for elements

Adding a label to an element

This chart lists all of the element types that can be labeled.

Packages Association/Aggregation role names

Use cases Events
Objects Types
Operations Activity Flows
Attributes Constraints
States Comments
Classes Requirements
Actors Files

To add a label to an element:

1. Right-click the selected element in the browser. (You can double-click to display the
Features window immediately.)

2. Select Features from the menu to display the Features window for the selected element.
In this example, the developer is labeling an event.

3. Click the L button next to the Name field. The Name and Label window displays.
4. Type the text in the Label field. The read-only Name field displays the name of the
element for reference.

5. Click OK twice.

Rational Rhapsody 329

Model elements

Note
Remember that these labels do not have any meaning in the generated code and are used
only as references to locate elements in diagrams and windows.

Removing a label from an element

To remove a label from an element:

1. Right-click the selected element in the browser. (You can double-click to display the
Features window immediately.)

2. Select Features from the menu.

3. Click the L button next to the Name field to open the Name and Label window.

4. Clear the Label field.

5. Click OK twice.

Alternatively, you can set the label to have the same value as the Name. In this case, the label
becomes tied to the name. In this way, any changes made to the element name also affect the label.

Label mode
Rational Rhapsody differentiates between element names, which are used in the generated code,
and element labels, which are just used to represent elements in a user-friendly way within the
Rational Rhapsody interface.

Ordinarily, you must provide an element name, even if you are providing a label, and the name
must satisfy certain criteria, such as not containing spaces or special characters.

If you would like to deal exclusively with labels, you can select View > Label Mode. In this work
mode, you only have to provide a label for elements. Rational Rhapsody automatically converts
the label to a legal element name, replacing any characters that cannot be used in element names.
The text that you entered as the label will be shown in the browser, graphic editor, and the Features
window.

Note
When Label Mode is selected, Rational Rhapsody ignores the radio button selected under
Display Name in the Display Options window. Label Mode is a per-user setting. If the
project is opened on a different user's computer, it is displayed in normal mode unless that
user has selected Label Mode.

330 User Guide

 Modify elements

Modify elements
You can move, copy, rename, delete, and re-order elements. In addition, you can display
stereotypes of model elements, create graphical elements, and associate an image file with a model
element.

Moving elements
To move elements, use any of the following methods:

You can move all elements within the browser by dragging-and-dropping them from one
location to another, even across packages.
You can move a group of highlighted items to a new location in the project by dragging
and dropping them into that location in the browser.
In addition, you can drag-and-drop packages, classes, actors, and use cases from the
browser into diagrams.
If code has already been generated for a class or package, you can open the code by
dragging and dropping the class or package from the browser into an open editor, such as
Microsoft Word™, Visual C++, Borland C++, or Notepad. If the code exists, the standard
“+” icon displays as you drag the element into the editor. If the “+” icon does not appear,
most likely code has not yet been generated for the element. If the element has both a
specification and an implementation file, both files are opened.
See Smart drag-and-drop.

Note
Do not try to open the code for a class or package by dragging it from an object model
diagram because this removes the element from the view.

Rational Rhapsody 331

Model elements

Copying elements
To copy elements, use any of the following methods:

You can copy all elements within the browser by dragging-and-dropping.

To copy an element, press the Ctrl key while dragging the element onto the new owner.
See Smart drag-and-drop.

Copying an element into the same namespace, such as within its own package, creates a copy with
the suffix _copy appended to its name. For example, copying a class Sensor into the same package
as the original creates a class named Sensor_copy. Subsequent copies have a suffix of _copy_<n>,
where <n> is an incremental integer starting with 0.

Copying an element into a different namespace creates a copy with exactly the same name.

Renaming elements
Renaming requires a valid name that does not already exist. An appropriate message is displayed if
either condition is not met, and the name reverts to its previous value.

There are two methods for renaming elements. You can edit the Name box of the Features window
or you can edit the name directly in the browser.

1. Click once on the element name to select it.

2. Click once again to open the name field for editing. An edit box opens with the name
selected, as shown in the following example.

3. Edit the name and press Enter, or click once outside the edit field to complete the change.

The other method you might use is the Features window.

1. Open the Features window for the element.

2. Type the new name in the Name box.

3. Click Apply, or anywhere outside of the Features window, to apply the new name.

4. Click OK.

Note
Do not use this method to rename the project.

332 User Guide

 Modify elements

Deleting elements
The Edit menu on the diagram editors contains the Remove and Delete menu commands.
Edit > Remove removes an object from a particular view but not from the model, whereas Delete
deletes the item from the entire model. In the browser, Delete always deletes an object from the
entire model, including all diagrams.

To delete an object from the entire model while in the browser, use any of the following methods:

Select the item and then choose Edit > Delete.

Right-click the item, then select Delete from Model.
Select the item and press the Delete key.
If you delete the only item in a category, the entire category displays with it. For example, if you
delete the only object model diagram, the entire Object Model Diagrams category displays along
with the specific diagram you deleted. The category does not return to the browser until you create
at least one object model diagram.

Editing multiple elements

To edit multiple elements of the same metatype at the same time:

1. In the browser, highlight the elements that are all members of the Attributes, Types,
Dependencies, Packages, Operations, or Classes metatype.

2. Right-click and select Features. The Features window displays as Multiple Selection
with only the General tab accessible. (The Name and Label fields are disabled.)

Rational Rhapsody 333

Model elements

3. Type the change to common element items such as the stereotype, description, or type
definitions.

Note: If all of the selected elements have the same values, the new values are applied
to all. However, if the selected elements have different values, the Multiple
Selection window uses the Keep Original Values option to pinpoint those
areas containing varying values. Select this option to keep the different values
in the selected elements when the change is applied.
4. Click OK.

Re-ordering elements in the browser

By default, model elements are ordered alphabetically within each category. However, Rational
Rhapsody also allows you to manually reorder elements within each category.

You might want to reorder elements in the browser in order to:

move important items higher in the list

control the order of model elements in the generated code. The order of elements in the
generated code is determined by the order of display in the browser. To control the order
of elements in the generated code, reorder the relevant elements in the browser before
generating the code.

Note
Currently, Rational Rhapsody allows you to rearrange all model elements except for
statechart-related elements and activity diagram-related elements.
By default, the ability to reorder elements in the browser is disabled. To enable element reordering,
select View > Browser Display Options > Enable Order from the menu.

When the re-ordering option is available, you can reorder elements:

1. Select the element you would like to move.

2. Click the Up or Down arrow in the browser toolbar to move the element.

Note
The Up and Down arrows are only displayed after you have selected a movable model
element. If the element is at the top of a category, only the Down arrow is accessible when
you are selecting the element. If the element is at the bottom of the category, only the Up
arrow is available upon selection.

334 User Guide

 Modify elements

Displaying stereotypes of model elements

Rational Rhapsody provides the option of displaying the stereotypes applied to a model element,
alongside the name of the element in the browser.

To display elements’ stereotypes in the browser, use one of these methods:

From the menu, select View > Browser Display Options > Show Stereotype > All
At the project level, modify the property Browser::Settings::ShowStereotypes. The
possible values for this property are No, Prefix, Suffix.

Note
When All is selected, the property is assigned the value Prefix. When None is selected,
the property is assigned the value No. If you want the stereotype name displayed after the
element name, this can only be done by changing the property directly to Suffix.

If you select the option First, then for elements with more than one stereotype, only the first
stereotype is displayed in the browser.
The default setting for the property Browser::Settings::ShowStereotypes is Prefix. For
projects created with Rational Rhapsody 6.0 or earlier, this property is overridden and set to No.

This settings does not apply to stereotypes that are defined as “new terms.” When a stereotype is
defined as a “new term,” it is given its own category in the browser, and any elements to which this
stereotype is applied are displayed under the new category.

Rational Rhapsody 335

Model elements

Creating graphical elements

You can create graphical representations for elements in a model and place them in diagrams. This
technique is often used to represent all visible behavior in a use case diagram. This feature is often
used to represent stereotypes and tags in diagrams.

To create a graphical representation for an element that is listed in the browser, but not shown in
the diagram:

1. Locate the element in the browser that is not currently graphically represented in a
diagram. Highlight and drag the element into the diagram.

2. The element displays in the diagram, where you can use the Features window to make any
changes and additions to the description for the element.

3. If they can be connected semantically, you might also link the new graphical element to
other diagram elements in the diagram. For example, a stereotype can connect to another
stereotype for inheritance.

Moving the element into the diagram functions as a move of a class or object.

Supported image formats

The following graphic formats are supported for associated image files: jpeg, tiff, bmp, ico, emf,
tga, pcx.

Associating an image file with a model element

Rational Rhapsody allows you to associate an image file with a model element. This image can
then be used to represent the element in diagrams in place of the standard graphic representation.

To associate an image file with a model element:

1. Right-click the relevant element in the browser, and then select Add Associated Image.

2. When the file browser window is displayed, select the appropriate image file.

Displaying associated images

Once an image file has been associated with a model element, it can be displayed in diagrams that
contain that element.

To display the image associated with an element in a diagram, rather than the regular graphical
representation:

1. Open the Display Options window.

2. Select Enable Image View.

336 User Guide

 Modify elements

3. Choose Use Associated Image or, alternatively, choose Select an Image and click ... to
open the file browser.

To enable the display of associated images at the diagram level, set the property
General::Graphics::EnableImageView to Checked. The default value is Cleared.

When using an associated image in a diagram, there are a number of ways the image can be
displayed:

Image Only displays the image instead of the regular graphic representation.
Structured displays the image within the regular graphic representation.
Compartment displays the image within a compartment together with the other items that
are displayed in compartments, for example, attributes and operations.
To select one of these layout options:

1. In the Display Options window, click Advanced.

2. When the new window opens, select one of the layouts.

3. Click OK.
To set the image view layout at the diagram level, select the appropriate value for the property
General::Graphics::ImageViewLayout. The default value is ImageOnly.

Restoring image size, proportions

When Image Only has been selected as the image layout option, the context menu displayed when
right-clicking the image contains two additional options under the menu item Image View:
Restore Initial Size and Restore Initial Proportions.

Modifying, replacing, and removing associated image files

Once an image has been associated with a model element, a menu item called Associated Image
will be available in the context menu that is displayed when the element is selected in the browser.
This item contains the following options:

Open Image allows you to view the image in an external viewer. The application that is
opened is determined by two properties. If the property General::Model::ImageEditor
is set to the value AssociatedApplication, the default application for this type of file
will be launched. However, if this property is set to ExternalImageEditor, the
application launched will be the application specified with the property
General::Model::ExternalImageEditorCommand. The value of this property should be
the command-line for launching the relevant application.
Replace Image displays a file browser, allowing you to select a new image file to
associate with the model element, replacing the current associated image.

Rational Rhapsody 337

Model elements

Remove Association breaks the association between the model element and its associated
image file.

Compatibility with previous image association mechanism

While the procedure described in this section is the current way to associate an image file with a
model element, Rational Rhapsody still supports the old approach of associating a stereotype with
a bitmap file. If you have defined such stereotypes, simply select Enable Image View in the
Display Options window to display the image.

Controlled files and image association

If you add an image file as a controlled file beneath a model element, the image file is
automatically associated with the model element.

338 User Guide

 Smart drag-and-drop

Smart drag-and-drop
This section describes how to operate the Rational Rhapsody smart drag-and-drop feature. It
provides step-by-step instructions for performing smart drag-and-drop operations.

To drag-and-drop a class:

1. Expand your browser view so that all classes are viewable.

2. Click a class in the browser and while holding the mouse button down, drag the class onto
another class; before releasing the mouse button press the Shift key.

Note
You must press and hold the Shift key before releasing the mouse button when dragging-
and-dropping a class.
3. A context submenu displays. Select the wanted option. In the example, the Tank class is
being dragged onto the AbstractFactory class.

4. In this example the Tank class will be added as a dependency.

Rational Rhapsody 339

Model elements

5. Once a selection is made from the submenu, the browser opens the feature added (in this
case, the dependency).

340 User Guide

 Smart drag-and-drop

6. If the class selection (Tank) were being made a superclass, it would appear a
dependency added as a superclass.
.

7. If the class selection (Tank) were being copied to another class (Abstract Factory), it
would appear as shown in the following figure. Note that the class attributes for Tank
remain intact.

Rational Rhapsody 341

Model elements

Searching in the model

Engineers and developers can use the Rational Rhapsody Search and Replace facility for simple
search operations. To perform quick searches with commonly used filters such as wildcards, case,
and exact string, select Edit > Search to display this window.

To display new search results in a separate tab of the Output window, select the New Tab check
box and enter new search results and click Find.

You can also highlight an item in the browser and search only in that part of the project by
selecting Edit > Search In. If you want to perform more complex searches, click Advanced in
this window.

Finding element references

The References feature enables you to find out where the specified element is used in the model.

1. Highlight an element in the browser.

2. Select Edit >References. The Relations window opens, listing the locations of the
element in the model.

342 User Guide

 Searching in the model

If the element is not used anywhere in the model other than in the browser, Rational Rhapsody
displays a message stating that the element is not referenced by any element.

References option returns only model elements that actually reference the specified element; it
does not return references to the textual name of the element. To do a text-based search for the
element name, use the search and replace functionality described in Searching in the model.

Note
You can also display the list of references by using the keyboard shortcut CTRL+R.

Advanced search and replace features

To manage large projects and expedite collaboration work, complex searches are often needed. For
those types of searches, select Edit > Advanced Search and Replace. The advanced facility
provides the following additional capabilities:

Locate unresolved elements in a model

Locate unloaded elements in a model
Identify only the units in the model
Search for both unresolved elements and unresolved units
Perform simple operations on the search results
Create a new tab in the Output window to display another set of search results

Rational Rhapsody 343

Model elements

All search results display in the Output Window with the other tabbed information. Search and
replace results display at the bottom of the Find window, as shown in the example. For more
information about the uses of this facility, see Advanced search and replace features.

Using the auto replace feature

To perform a search and replace operation with an automatic replace:

1. Choose Edit > Advanced Search and Replace.

2. Enter the Find what and Replace with text in those two fields.

3. Click Auto Replace. The changes display at the bottom of the window.

This automatic replacement also performs an automatic commit of the changes into the Rational
Rhapsody model so that you do not need to apply the changes manually. However, it does not
display any ripple effects of the change.

The Auto Replace feature cannot be used on the following items because they do not qualify to be
replaced automatically:

Read-only elements.
A description that includes hyperlinks
Stub or unresolved element names
The name of an event reception, constructor, destructor, generalization, or hyperlink

344 User Guide

 Searching in the model

Searching for elements

To search for specific elements in the model:

1. Choose Edit > Advanced Search and Replace to display the Advanced Search and
Replace window.

2. Click the Search elements tab to display this window.

3. Select any or all of the element types listed in the scrolling area. Use the Select All, Clear
All, or Invert to select element types quickly.

4. Click Find. The results display at the bottom of the window.

5. Highlight an item in the search results and right-click to perform either of these
operations:

References displays all of the relations to the selected element.

Delete from model.
6. If you double-click an element in the list, the Features window opens so you can see and
change the description and other characteristics for the element.

Rational Rhapsody 345

Model elements

7. You can also highlight an item and perform an Auto Replace, as described in Using the
auto replace feature.

Searching in field types

To search in specific fields within the model:

1. Choose Edit > Advanced Search and Replace to display the Advanced Search and
Replace window.
2. On the Search in tab, select the types of fields you want to find in the model by checking
them in the list at the top of the window.

3. The Element name, User code, and Other text check boxes display the fields associated
with them. For example, if only User code is checked, only the code-related fields
(Actions, Configuration initialization, Initial value, Operation bodies, and Type
declarations) are checked. Similarly, if only Other text is checked, only the text-related
fields are checked. The possible values are as follows:

Comment specification scans all the comment specifications for the specified
string
Configuration initialization scans all the configuration init code segments for
the specified string
Constraint specification scans all the constraint specifications for the specified
string (Chinese, Korean, Taiwanese, and Japanese are supported in this field and
stored as RTF.)
Descriptions scans all the descriptions for the specified string
Enumerationliteral value scans the literal value of the enumeration type for the
specified search string.
Initial value scans the initial value fields for attributes and arguments for the
specified search string
Label scans all the labels for the specified search string
Locally overridden property scans the locally overridden properties for the
specified search string.
Multiplicity scans the Multiplicity field of associations for the specified search
string.
Name scans all the element names for the specified search string
Operation bodies scans operation bodies, including operations defined under
classes, actors, use cases, and packages for the specified search string
Requirement specifications scans all requirement specifications for the specified
search string. (Chinese, Korean, Taiwanese, and Japanese are supported in this
field and stored as RTF.)

346 User Guide

 Searching in the model

Tag Value scans the value of the tags for the specified search string.
Activity Flow Label scans all activity flow code (action, guard, trigger) for the
specified search string.
Type declarations scans all the user text in “on-the-fly” types for the specified
search string.
4. You can also specify that the Element name, User code, and Other text be included or
excluded from the search.

5. Click Find to list the fields that meet your search criteria at the bottom of the window.

You can highlight an item in the list and replace it.

Rational Rhapsody 347

Model elements

Previewing in the search and replace facility

After performing a search, you can highlight and item in the search results and click the Preview
tab. This displays the occurrence of the highlighted item so that you can see and perhaps change
the string.

Use the following buttons to make changes to the selected occurrence:

Find Next highlights the next occurrence of the string in the same file.
Replace replaces the highlighted occurrence of the original string with the replacement
string specified on the Find/Replace tab.
Replace All replaces all occurrences of the string.
Apply applies the changes done in the Preview tab (editing or replacing text) to the
Rational Rhapsody model.
Cancel cancels the search and replace.
Auto Replace automatically replaces all occurrences of the highlighted string with a
replacement string.

Note
If you make a mistake, select Edit > Undo to undo the changes.

348 User Guide

 Controlled files

Controlled files
Rational Rhapsody allows you to create controlled files and then use their features.

The model in this section uses the “Cars” C++ sample (available in the <Rational Rhapsody
installation path>\Samples\CppSamples\Cars) to demonstrate how to use controlled files.

Controlled Files, such as project specifications files (for example, Microsoft Word,
Microsoft Excel files) are typically added to a project for reference purposes and can be
controlled through Rational Rhapsody.
A controlled file can be a file of any type (.doc, .txt, .xls, and so on).
Controlled files are added into the project from the Rational Rhapsody browser.
Controlled files can be added to diagrams via drag-and-drop from the browser.
Currently, only Tag and Dependency features can be added to a controlled file.
By default all controlled files are opened by their Windows-default programs (for
example, Microsoft Excel for .xls files).
The programs associated with controlled files can be changed via the Properties tab in the
controlled files window.

Rational Rhapsody 349

Model elements

Creating a controlled file

Controlled files can be created using many methods. A controlled file can be created by browsing
and selecting a file from the file system or by using a command. To select a method:

1. To select the way a controlled file is created, double-click a package in the Rational
Rhapsody browser and select the Properties tab from the Features window.

2. With the All filter selected, expand the section Model and expand the ControlledFile
subsection. The property NewPolicy controls the way a controlled file is created. The
default selection is SystemDefault. The property can be set to UseOpenCommand or
UseRhapsodyCodeEditor.

SystemDefault: This setting lets the program (as done in hyperlink, for example),
open the file according to the MIME-type mapping.
UseOpenCommand: This setting means that double-clicking on the controlled
file runs the open command. The open command is set in the OpenCommand
property (Model/ControlledFile/OpenCommand). This is a string property that
expands the keyword $fileName to the full path of the Controlled File. In the
event of property inconsistency, where the program is set to run the
UseOpenCommand but the command contains no setting, the SystemDefault
policy will be used.
UseRhapsodyCodeEditor: This setting allows the file to be opened within the
internal Rational Rhapsody code editor.
If you want to open the controlled file after it is created, set the value of the property
OpenFileAfterCreation to yes. The file will open the file immediately after it is created.

350 User Guide

 Controlled files

Browsing to a controlled file

This section describes how to create a controlled file by browsing to it.

1. To create a controlled file, right-click a non-read-only element, such as a package, in the

browser and select Add New > Annotations > Controlled File. The Select Controlled
File open window opens.

Note: Add New > Annotations is the default menu command structure in Rational
Rhapsody. It can be changed by users. This topic assumes that all defaults are
in place.
2. Navigate to the wanted file and click the Open button. Unless the controlled file being
selected is located in the right location under the _rpy directory (cars_rpy in the example),
a message displays asking you for permission to copy the file. If you do not want the file
copied into the _rpy directory, you must place the original into the _rpy directory before
selecting it from the Rational Rhapsody browser.

3. A window displays asking you for permission to copy the file into the _rpy directory.
Click OK.

4. The controlled file now displays in the Rational Rhapsody browser.

Rational Rhapsody 351

Model elements

5. Controlled files can be added to the graphic interface (right window pane) via drag-and-
drop from the browser.

Controlled file features

Controlled files can be any standard Windows type, such as .doc, .txt, and .xls. When those
files are opened in Rational Rhapsody, they are displayed in their Windows-default programs,
such as for Microsoft Excel for .xls files. In addition, the programs associated with controlled
files can be changed via the Properties tab in the controlled files window.

352 User Guide

 Controlled files

Adding dependencies to controlled files

Dependencies can be added to controlled files to display what object depends on the controlled file
or what object the controlled file is dependent upon.

To add a dependency to a controlled file (through the Rational Rhapsody browser):

1. To add a new dependency, right-click the controlled file and select

Add New > Relations > Dependency.

Note: Add New > Relations is the default menu command structure in Rational
Rhapsody. It can be changed by users. This topic assumes that all defaults are
in place.
2. Make a selection in the window that displays and click OK.

3. Type the name of the dependency, or leave the default name.

4. Double-click the dependency in the browser to modify it.

To add a dependency to a controlled file (via Graphic Pane):

1. Drag the controlled file from the browser into the graphic pane, if you have not already
done so.

2. Using the dependency icon , draw a dependency line from the controlled file to the
wanted object.

Rational Rhapsody 353

Model elements

Adding tags to controlled files

Tags can be added to controlled files for purposes such as identification. For instance, tagging all
controlled files that are related to the specification for a product helps differentiate those controlled
files from other controlled files that might be embedded in the project.

To add a tag to a controlled file (via the browser):

1. Right-click the controlled file and select Add New >Tag.

2. Type a name for the tag or leave the default name.

3. Double-click the tag in the browser to modify it.

To add a tag to a controlled file (via the Features window):

1. Right-click the controlled files in the browser and select Features.

2. The Features window displays. Click the Tags tab and enter the name of the tag in the
“Quick Add” section at the bottom of the window. Click the Add button.

3. Click OK.

354 User Guide

 Controlled files

4. Expand the Controlled File by clicking on the “+” next to it in the browser.

5. The Tags listing displays. Click the “+” next to the Tags listing to see the new Tag you just
created.

Configuration management
Configuration management options are as follows:

Configuration
Feature Description
Management Feature
Add to Archive This feature is used when a you want to add a new file into the
configuration management server for the first time. After that, other
users can check in/out, lock/unlock the file.
Check In This feature checks the file into the configuration
management server so that other users can modify the file. You still
have read-only access to the file, but you cannot modify it.
Check Out This feature checks the file out of the configuration management
server so that other users cannot modify the file. Other users can open
the file for read-only
purposes.
Lock This feature locks the file so that other users cannot modify it in the
future. Only you can unlock the file.
Unlock This feature unlocks the files so that other users can modify the file in
the future. Only you can unlock the file.

Rational Rhapsody 355

Model elements

Troubleshooting controlled files

Following is a list of the most commonly encountered problems with their solutions:

Question: “I checked out a controlled file. But I am not able to change its description,
properties, and so on.”

Answer: The metadata for the controlled file is stored in it's parent element. So you must
check out the parent element in order to change any associated information, such as the
description, properties, and so on.
For instance, in the example provided in Creating a controlled file,
right-clicking on the parent element RailCarsPackage and choosing Configuration
ManagementCheck out, allows the controlled file attributes to be modified.

Question: “I know controlled files are copied to a directory under _rpy during the creation
of the controlled file, but where exactly is the controlled file copied?”

Answer: Controlled Files are copied to the same location where its parent is located on
the disk. For instance, suppose you have a package called “package_1” and the repository
file for it is stored like this: MyProject_rpy\package_1\package_1.sbs.
Now any controlled file you add to the package “package_1” is going to be stored in the
folder: MyProject_rpy\package_1\

Question: “When I open a Controlled File Features window and try to rename the
Controlled File, I receive the ‘File not found’ error.”

Answer: You have the ability to select different files from an opened Features window. So
when you type a different name, the system “thinks” that you are actually trying to point
to a different file and returns an error message.

You can rename a controlled file from the browser by clicking two separate times on it
(double-clicking on the file will open it).
Question: “Is it possible to add a Controlled File to the model without copying the file to
the _rpy folder?”

Answer: No, but you can add a hyperlink to the wanted file instead. However, this will
result in the loss of all CM (Configuration Management) capability which includes the
following operations:
– Add to archive
– Check in
– Check out
– Lock
– Unlock

356 User Guide

 Controlled files

Issue: Configuration management (CM) operations on Controlled files fail on some

occasions.
Details: If you are using CM in command mode, make sure the file is located under the
_rpy folder. In order to perform Configuration Management operations in command mode
from Rational Rhapsody, the file (other than the project itself) has to be under the _rpy
directory. There is no current fix for this issue.

Workaround: Create a new package under the project. By default, a package is stored in
separate file: do not modify that setting. Now add the problematic controlled files to this
package. Now you will be able to perform CM operations.
Issue: Adding an existing element with a Controlled File to the Model and choosing a
different name, instead of replacing the file.
Details: If you perform an Add To Model of an already existing element, Rational
Rhapsody gives you the option of replacing the element or adding it using a different
name. If you choose to use a different name, Rational Rhapsody adds the element using
the new name.

If both the element that already existed in the model and the element that was just added
have controlled files by the same name, more than one controlled file of the same name
exists in the model. But there might be only one instance of the file in the directory, which
means the two controlled files in the model are actually pointing to the same file.

Controlled file limitations

General limitations
Connecting to Archive Error:

If your configuration management tool is Rational ClearCase, this Connecting to Archive

limitation applies to you.

If you are trying to “Connect to Archive” using the Configuration Items tool (File/
Configuration Items), and your Rational Rhapsody project contains a controlled file, the
following error results:

Cannot perform Connect to Archive.

Reason: Rational Rhapsody could not add “Project_rpy” to Source Control as the project
contains at least one Controlled File. To proceed, add this directory (and its
subdirectories) to Source Control using Rational ClearCase. Note that, you do not need to
Connect to Archive again.

Use Rational ClearCase to add the directory to the appropriate source control. You now
do not have to perform a “Connect to Archive.”

Rational Rhapsody 357

Model elements

Deleting an Element with a Controlled Files Deletes the Controlled File From the
Model Only.

If you delete a controlled file from a Rational Rhapsody Model, you are given the option
to either delete the file completely from the hard disk drive or leave the file intact and
simply delete the controlled file from the model. If you delete any other element that
includes a controlled file (as a child), the controlled file is left intact on the hard disk; the
option to delete the controlled file completely from the hard disk drive is not offered.
Moving a Controlled File - Browser vs. Graphic Editor

If you have two packages stored in different directories (P1 and P2 for this example), and
you add a controlled file to the P1 directory, the physical controlled file on the hard disk is
stored in P1's directory (the same directory where P1.sbs file is located).

From the Rational Rhapsody browser, drag the controlled file from P1 and drop it in the
P2 package. Now examine the contents of the P1 and P2 directories on the hard disk.
Notice that the file has moved from the P1 directory to the P2 directory.

If you repeat the above exercise in the Rational Rhapsody Graphic Editor, the physical
file is copied from the old directory to the new directory, instead of being completely
moved from the old directory to the new directory.
Configuration Management Synchronize window Does Not Show Controlled Files

Configuration Management's Synchronize window shows items that are modified by

other users but not yet loaded into your model. This window does not hold true for
controlled files. The synchronize window does not display Controlled Files when there
are newly-updated controlled files in the Configuration Management system.
Controlled Files Version Number Not Shown In the Configuration Management
Window

The Configuration Management window shows the version number for the items in its
listing (only in command mode). But for a controlled file, it does not show the version
number.
Foreign Language Controlled File Names are Not Supported

If your file name has non-English characters, you cannot add it to your project as a
controlled file.
CM Archive is Not Affected When Controlled Files are Moved/Renamed/Deleted

When you move, rename or delete a Controlled File, its respective Configuration
Management item is not updated accordingly.

358 User Guide

 Controlled files

DiffMerge limitations
Diffmerge Does Not Compare the Contents of Two Controlled Files

Diffmerge does not identify/indicate any content differences between two controlled files.
Diffmerge does not examine the contents of controlled files as they exist on the hard disk
drive. However, Diffmerge can show differences between the metadata information of
two controlled files in the model.

Ex. Given two packages (Pkg1 and Pkg2) that each contain the controlled file readme.txt,
if the file contents of the Pkg1 readme.txt are different from the contents of the Pkg2
readme.txt then a Diffmerge performed between Pkg1 and Pkg2 will not identify that the
readme.txt files are different. However, if the Pkg1 readme.txt and Pkg2 readme.txt have
different metadata such as properties or description then those differences are shown in
the Diffmerge.
'Save merge as…' or 'merge back to rhapsody' Does Not Save Any Controlled Files

When using Diffmerge to compare two model units that contain controlled files,
performing the “Save merge as...” or “merge back to rhapsody” functions does not save
the controlled files on the hard disk drive.

Ex. Using the same example as above, if you compare Pkg1 with Pkg2 and save the
merge as “Pkg_Merged,” the physical file readme.txt for Pkg_Merged will not be saved
on the physical hard disk drive. If you were to navigate to the file under the appropriate
directory (c:\diffmerge for example), you would notice the readme.txt file does not appear
in that directory.

Search and replace limitations

Note
After performing a search using regular expressions, look inside the Preview tab in the
Search and Replace window. The Find Next, Replace, and Replace All functionalities
might not work for one or more selected search results.
This search and replace limitation is not limited to controlled files.

Rational Rhapsody 359

Model elements

Print Rational Rhapsody diagrams

The File menu includes the following print options:

Print Diagrams displays all the diagrams used in the model so you can easily select
which ones to print (see Selecting which diagrams to print)
Print displays the standard Print window, which enables you to print the current diagram
on the specified printer
Print Preview displays a preview of how the diagram will look when it is printed
Printer Setup displays the standard Print Setup window, which enables you to change the
printer settings, such as landscape instead of portrait mode
Diagram Print Settings enables you to specify diagram-specific print options (see
Diagram print settings)

Selecting which diagrams to print

Rational Rhapsody enables you to print multiple diagrams.

1. Choose File > Print Diagrams. The Print Diagrams window opens, listing the diagrams
and statecharts in the current project. The window has the following features:

The list box on the left shows all of the diagrams in the project.
The list box on the right shows the names and types (for example,
ObjectModelDiagram) of the diagrams selected for printing.
The buttons in the middle let you select and deselect diagrams for printing.
The Up/Down arrows on the far right control the order in which the diagrams are
printed.
The buttons along the bottom edge of the window access the Print window, or
cancel printing.
2. To expand the list of diagrams in the project, click the + sign to the left of one of the
diagram type names. The tree expands to show all the diagrams of that type. Note that
statecharts are listed first by package, then by class.

3. Do one of the following actions:

a. To add a diagram to the print list, select it in the list on the left and click Add.

b. To add all the diagrams in the project to the print list, click Add All.

c. To remove a diagram from the print list, select it in the list on the right and click
Remove. Rational Rhapsody prints the diagrams listed in the right from top to
bottom.

360 User Guide

 Print Rational Rhapsody diagrams

d. To change the print order, select a diagram from the print list and use the up or down
arrows.

4. Click the appropriate button:

a. Print dismisses the Print Diagrams window and opens the standard Print window for
your operating system. In this window, you set attributes such as page size (for
example, 11” x 17”), the printer to use, whether to print to a file, whether to use
grayscale, and initiate the printing operation.

b. Cancel cancels the print operation and dismisses the window.

Rational Rhapsody 361

Model elements

Diagram print settings

File > Diagram Print Settings lets you specify diagram-specific print settings that can be retained
between Rational Rhapsody sessions. This option is particularly useful for complex and multipage
diagrams.

The window contains the following fields:

Orientation specifies the page orientation

Scaling specifies the scale percentage, or whether to shrink the diagram so it fits on one
page.
Options specifies whether to:
– Print the background color.
– Include a header or footer on the printout.
– Retain your diagram settings across Rational Rhapsody sessions.

By default, the header includes the name of the diagram, and the footer
contains the page number. To specify a new header or footer, uncheck the
appropriate check box and type the new value in the text box.
For example, to include the name of your company in the diagram header:

1. Clear the Add diagram name in header check box.

2. In the text box, type the name of your company.

3. Click OK.

4. Use one of the Print options to print out the diagram.

362 User Guide

 Print Rational Rhapsody diagrams

Using page breaks

Rational Rhapsody can break a large diagram across several pages or scale it down so it fits on a
single page, depending on your preference.

To scale the diagram so it fits on a single page, right-click in the diagram and select Printing > Fit
on One Page. To break the diagram across pages, simply disable this option.

To view the page breaks in a diagram, do one of the following actions:

Click the Toggle Page Breaks tool to toggle the display of page breaks in your diagram.
Select Layout > View Page Breaks.
Right-click in the diagram and select Printing > View Page Breaks. The dashed lines that
represent the page boundaries are displayed.

Rational Rhapsody 363

Model elements

Exporting Rational Rhapsody diagrams

To export any Rational Rhapsody diagram:

1. Display the diagram.

2. Right-click inside the diagram, but not on a specific item in the diagram.

3. From the displayed menu, select Export Diagram Image.

4. In the Save As window, select a directory for the saved image in the Save in directory
selection field.
5. In the File name field, type the name you want to use for the exported image file.

6. In the Save as type field, select one of these image types:

7. Click Save to complete the export process.

364 User Guide

 Annotations for diagrams

Annotations for diagrams

You can add different types of annotations to specify additional information about a model
element. The annotation can add semantics (like a constraint or requirement) or can simply be
informative, like a documentation note or comment.

Note
None of the annotation types generate code; they are used to improve the readability and
comprehension of your model.
Constraint for a condition or restriction expressed in text. It is generally a Boolean
expression that must be true for an associated model element for the model to be
considered well-formed. A constraint is an assertion rather than an executable
mechanism. It indicates a restriction that must be enforced by the correct design of a
system.

Constraints are part of the model and are, therefore, displayed in the browser.
Comment for a textual annotation that does not add semantics, but contains information
that might be useful to the reader and is displayed in the browser.
Note for a textual annotation that does not add semantics, but contains information that
might be useful to the reader. Notes are not displayed in the browser.
Requirement for a textual annotation that describes the intent of the element. Note that a
requirement modeled inside Rational Rhapsody does not replace the usage of a dedicated
requirement traceability tool, such as DOORS. Instead, a modeled requirement
complements the usage of such a tool because the hierarchical modeling of requirements
enables you to easily correlate each requirement to the element that addresses it.

Requirements are part of the model and are therefore displayed in the browser.

Rational Rhapsody 365

Model elements

Creating annotations
To add an annotation to a diagram:

1. Click the appropriate icon in the Diagram Tools for the type of annotation you want to
create.

2. Single-click or click-and-drag in the diagram to place the annotation at the intended

location.

3. Type the note text or expression.

4. Press Ctrl+Enter to terminate editing.

The same annotation can apply to more than one model element and multiple annotations can
apply to the same model element. You can use “ownership” instead of an anchor. For example, if a
requirement is owned by a class, it is a requirement of the class.

The new annotation is displayed in the diagram, and in the browser if it is a modeled annotation.
Note that documentation notes and text are graphical annotations and exist only in the diagram; all
the other Rational Rhapsody annotations are modeled annotations, and are part of the model itself.
Because modeled annotations are part of the model, they can be viewed in the browser. In addition,
you can move modeled annotations to new owners using the browser, and can drag-and-drop them
from the browser into diagrams. Modeled annotations are displayed under separate categories in
the browser by type.

Alternatively, you can create modeled annotations in the browser, as follows:

1. Right-click the element that needs the annotation.

2. Select Add New > Annotations > Constraint, Comment, or Controlled File. The new
annotation is added under the selected element.

An annotation created using the browser does not anchor the annotation to the specified model
element. However, you can organize annotations so that anchoring is implied.

366 User Guide

 Annotations for diagrams

Creating dependencies between annotations

You can show dependencies between annotations using the Dependency icon in the Diagram
Tools.

To create dependencies between annotations:

1. Click the Dependency icon in the Diagram Tools.

2. Click the edge of the dependent annotation.

3. Click the edge of the annotation on which the first annotation depends.

Creating hierarchical requirements

You can create hierarchical requirements by having one requirement own all the subrequirements;
the owning requirement is called the “sum requirement.”

1. In the browser, right-click the component that will own the requirement and select Add
New > Requirement.

2. Name the new requirement. This is the sum requirement.

3. Right-click the sum requirement and select Add New > Requirement.

4. Name the subrequirement.

5. Continue creating subrequirements as needed.

6. Create dependencies between the requirements as needed.

The following figure shows a hierarchical requirement.

Rational Rhapsody 367

Model elements

Editing annotation text

To edit the text of an existing annotation, do one of the following actions:

Double-click the annotation.

Right-click the annotation and then select Features.

Defining the features of an annotation

The Features window enables you to change the features of an annotation, including its name type.
The following figure shows the Features window for an annotation (in this case, a constraint).

A constraint contains the following fields:

Name specifies the name of the constraint. To enter a detailed description of the
constraint, click the Description tab.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the constraint, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.

368 User Guide

 Annotations for diagrams

– To select from a list of current stereotypes in the project, click the folder with

binoculars button.

– To sort the order of the stereotypes, click the up and down arrows button.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Type specifies the annotation type. For example, you could use this field to easily change
a constraint to a requirement or comment.
Defined in (read-only field) specifies the owning class of the annotation.
Specification specifies the note text or constraint expression.
Anchored Elements lists all the elements that are anchored to this annotation.

To view the features for an anchored element, select the element in

the list, then click the Invoke Feature Dialog button.

To anchor additional elements to this annotation, click the Select

button or the <Select> line in the list to select the elements from
the hierarchical display.

Rational Rhapsody 369

Model elements

Converting notes to comments

Documentation notes “live” only within diagrams. They are not displayed in the browser.

To convert a note to a comment (to be displayed in the browser), in the diagram, right-click the
note and the select Convert to Comment.

Anchoring annotations
You can anchor a constraint, comment, requirement, or note to one or more graphical objects that
represent modeling concepts (classes, use cases, and so on). You can also anchor annotations to
edge elements.

Although it is possible to anchor a requirement to an element, it is better to model it as a

dependency. Anchors are shown as dashed lines.

To anchor an annotation to a model element:

1. Click the Anchor icon in the Diagram Tools.

2. Click an edge of the annotation.

3. Move the cursor to the edge of the model element to which you want to anchor the
annotation, then click to confirm.

To change the line style of an anchor, right-click the anchor line and select the appropriate option
from the Line Shape menu.

Note the following information:

There should be only one anchor between a specific annotation and a given model
element.
An annotation can be anchored to more than one element.

Finding constraint references

To find which annotations are anchored to a particular class:

1. In the browser, select the class you want to query.

2. Select References from the menu. The References window lists all the references for the
specified class. Anchored annotations are labeled “Anchor” in the Type column.

370 User Guide

 Annotations for diagrams

Deleting an anchor
To delete an anchor:

1. Select the anchor.

2. Click the Delete tool in the main toolbar.

Rational Rhapsody 371

Model elements

Changing the display options for annotations

To change the display of annotations, right-click the note in the diagram and select Display
Options.

The Display Options window for the selected annotation type opens, with only the relevant fields
displayed. All of the fields are as follows:

Show specifies which information to display for the annotation:

– Name displays the name of the annotation
– Label displays the label for the annotation
– Specification displays the contents of the Specification field of the Features
window for the annotation
– Description displays the contents of the Description field of the Features
window for the annotation
Form specifies the graphical form of the annotation:
– Plain shows the annotation without a border, as free-floating text
– Note Symbol shows the annotation within a frame, with a symbol in the
upper, left-hand corner to denote the annotation type
– Pushpin displays the annotation with a rectangular border and a pushpin icon

372 User Guide

 Annotations for diagrams

The following figure shows some of the different display options. The annotation types and
display options are as follows:

Comment, displayed with its specification label using the pushpin style
Requirement, displayed using its label
Documentation note
Constraint
Text note

Deleting an annotation
To delete an annotation, on the browser, right-click the annotation to be deleted and select Delete
from Model.

To delete an annotation from a diagram, right-click the note and do one of the following actions:

Select the Delete icon from the toolbar.

Select Delete from Model from the menu.

Rational Rhapsody 373

Model elements

Using annotations with other tools

The following table lists the effect of annotations on both Rational Rhapsody and third-party tools.

Tool Description
COM API Annotations are supported by the COM API via the following interfaces:
• IRPAnnotation
• IRPComment
• IRPConstraint
• IRPRequirement
Complete Relation When you select Layout > Complete Relations, anchors are part of the information
added to the diagram.
DiffMerge Annotations are included in difference and merge operations.
Populate Diagram Annotations and anchors are not supported.
References If you use the References functionality for a modeled annotation, the tool lists the
diagrams in which the specified annotation displays. When you select a diagram from the
returned list, the annotation is highlighted in the diagram.
If you use the References functionality for an element, the tool includes any annotations
that are anchored to the specified element
For more information on this functionality, see Searching in the model.
Report on model Modeled annotations are listed by type under the owning package. Graphical annotations
are not included in the list.
Rational Rose Notes in Rational Rose (which are not displayed in the browser) are imported as notes in
Rational RhapsodyAnnotations.

Search in model When you search in a model, the search includes modeled annotations, including
the Body section. When selected, the annotation is highlighted in the browser.
For more information on this functionality, see Searching in the model.

Annotation limitations
Note the following limitations for annotations:

You cannot anchor an annotation to an element that is represented by a line (such as a

message or activity flow).
You cannot drag-and-drop an anchor from the browser to a diagram.

374 User Guide

 Profiles

Profiles
A profile is a special kind of package that is distinguished from other packages in the browser. You
specify a profile at the top level of the model. Therefore, a profile is owned by the project and
affects the entire model. By default, all profiles apply to all packages available in the workspace,
so their tags and stereotypes are available everywhere. A profile is very similar to any other
package; however, profiles cannot be nested.

A profile “hosts” domain-specific tags and stereotypes. Tags enable you to add information to
certain kinds of elements to reflect characteristics of the specific domain or platform for the
modeled system. Tags are easily viewable in their own category in the browser and in the Tags tab
of the Features window for an element.

You can apply tags to certain cases by associating the tag definition to stereotypes in a profile or a
package. In this case, the tags are visible only for those model elements that have the specified
stereotype. In addition, you can apply tags to individual elements.

The browser displays all of the profiles used in a project together, as shown in this example:

This example lists two profiles. MessageProfile is a user-defined (customized) profile. For more
information about these profiles, see Creating a customized profile. SPT was automatically added
to the project because the developer specifies the Scheduling, Performance, and Time method to
add timing analysis data. For more information, see Types of profiles.

Rational Rhapsody 375

Model elements

Creating a project without a profile

You are not required to use profiles in your Rational Rhapsody project. When creating a new
project, you can create a Default project, containing all of the basic UML features:

1. Create the new project by either selecting File > New, or click the New project icon in the
main toolbar.

2. Replace the default project name (Project) with <your project name> in the Project
name field. Enter a new directory name in the In folder field or Browse to find an
existing directory.
3. Select Default for the Project Type and Project Settings.

4. Click OK.

The basic structure for your new project is displayed in the browser with no Profiles folder.

376 User Guide

 Profiles

If you have a project that was created in an older version of Rational Rhapsody and you begin to
work on it in a newer version, Rational Rhapsody automatically inserts the required settings to
manage any compatibility issues.

Backward compatibility profiles

You might note any of the following backward compatibility profiles automatically loaded into
your project:

Pre60GESkin uses the colors and fonts from versions before Rational Rhapsody 6.0.
CGCompatibilityPre61C makes the code generation backwards compatible with pre-6.1
Rational Rhapsody in C models.
CGCompatibilityPre61Cpp makes the code generation backwards compatible with
pre-6.1 Rational Rhapsody in C++ models.
CGCompatibilityPre61Java makes the code generation backwards compatible with
pre-6.1 Rational Rhapsody in Java models.
CGCompatibilityPre61M1C makes the code generation backwards compatible with
pre-6.1 maintenance release 1 Rational Rhapsody in C models.
CGCompatibilityPre61M1Cpp makes the code generation backwards compatible with
pre-6.1 maintenance release 1 Rational Rhapsody in C++ models.
CGCompatibilityPre70C makes the code generation backwards compatible with pr-7.0
Rational Rhapsody in C models.
CGCompatibilityPre70Cpp makes the code generation backwards compatible with
pre-7.0 Rational Rhapsody in C++ models.
CGCompatibilityPre70Java makes the code generation backwards compatible with
pre-7.0 Rational Rhapsody in Java models.
CGCompatibilityPre71C makes the code generation backwards compatible with pre-7.1
Rational Rhapsody in C models.
CGCompatibilityPre71Cpp makes the code generation backwards compatible with
pre-7.1 Rational Rhapsody in C++ models.
CGCompatibilityPre71Java makes the code generation backwards compatible with
pre-7.1 Rational Rhapsody in Java models.
CGCompatibilityPre72C makes the code generation backwards compatible with pre-7.2
Rational Rhapsody in C models.
CGCompatibilityPre72Cpp makes the code generation backwards compatible with
pre-7.2 Rational Rhapsody in C++ models.
CGCompatibilityPre72Java makes the code generation backwards compatible with
pre-7.2 Rational Rhapsody in Java models.

Rational Rhapsody 377

Model elements

CGCompatibilityPre73Ada makes the code generation backwards compatible with

pre-7.3 Rational Rhapsody in Ada models.
CGCompatibilityPre73C makes the code generation backwards compatible with pre-7.3
Rational Rhapsody in C models.
CGCompatibilityPre73Cpp makes the code generation backwards compatible with
pre-7.3 Rational Rhapsody in C++ models.
CGCompatibilityPre73Java makes the code generation backwards compatible with
pre-7.3 Rational Rhapsody in Java models.
CGCompatibilityPre75C makes the code generation backwards compatible with pre-7.5
Rational Rhapsody in C models.
CGCompatibilityPre75Cpp makes the code generation backwards compatible with
pre-7.5 Rational Rhapsody in C++ models.

Types of profiles
Rational Rhapsody provides the following types of profiles:

Rational Rhapsody predefined Profiles, such as AutomotiveC and DoDAF, can be selected
from the New Project window when creating a new project or added to a project later, as
described in Adding a Rational Rhapsody profile manually.
User-defined profiles, as described in Creating a customized profile.
Add On product profiles, which require an additional license, are automatically added
when the engineer uses the associated add-on product, or it can be added using File >
Add Profile to Model.

Converting packages and profiles

You can convert any existing package into a profile and vice versa. To convert a package,
right-click the package in the browser, then select Change to > Profile. Similarly, to convert a
profile to a package, right-click the profile in the browser, then select Change to > Package.

Profile properties
By default, all profiles apply to all packages available in the workspace. To associate existing
profiles with new Rational Rhapsodyannotation models, use the following properties (under
General::Profile):

AutoCopied specifies a comma-separated list of physical paths to profiles that will

automatically be copied into new projects when they are created. By default, this property
is an empty string.

378 User Guide

 Profiles

AutoReferences specifies a comma-separated list of physical paths to profiles that will

automatically be referenced by new projects when they are created. By default, this
property is an empty string.
Note that you can specify packages in the property values. The paths can be disks, networks, or
Universal Naming Conventions (UNC), and the extension .sbs is optional. If Rational
Rhapsodyannotation cannot find at least one of the specified profiles, it generates an error
message.

You can use profiles like any other package, including exchanging them between users and using
configuration management tools with them.

Use a profile to enable access to your custom help file

This section shows you how you can enable access to your custom help file from within Rational
Rhapsody with the use of the F1 key. This feature is applicable for a Rational Rhapsody project
that has a Rational Rhapsody profile with a New Term stereotype defined for the profile. For
information about profiles, see Profiles. For information about stereotypes, see Stereotypes.

As referred to by Rational Rhapsody, a custom help file consists of a help file and a map file, both
of which you must create. There might be times when you have a project for which you would like
to access your own help file. This might be particularly useful when there is a team working on the
same project and you want them to share the same specific information. For example, your
company might create its own help file to document its project terminology and project/corporate
standards.

To enable the ability to access your custom help file from within Rational Rhapsody, you have to
set properties to identify and locate your custom help file and map file. Then for an element
associated with the New Term stereotype in the Rational Rhapsody profile for your Rational
Rhapsody project, when a user presses F1 to call a help topic, your custom help file would open
instead of the main Rational Rhapsody help file.

Keep in mind that the Rational Rhapsody product provides you with an extensive help file that
always displays when there is no custom help file available.

Note
IBM is not responsible for the content of any custom help file and map file.

The creation, functioning, testing, and maintenance of a custom help file and map file are
the responsibilities of the creators of these files.

About creating your custom Help file and map file

A custom help file consists of a help file and a map file, both of which you create. See About
creating your custom help file and Creating your map file.

Rational Rhapsody 379

Model elements

About creating your custom help file

Your custom help file must be in HTML format. (Example help file name: myhelp.htm.)

If you plan to share the custom help file with team members, place it in a shared location on a
network. You identify this file and its location in the Model::Stereotype::CustomHelpURL
property, as detailed in Enabling access to your custom help file.

Creating your map file

The map file for your custom help file must contain one or more Rational Rhapsody resource IDs
for which the custom help is provided. A resource ID corresponds to a particular GUID element in
the Rational Rhapsody product. For example, for the Attributes tab, the resource ID is 161328.

To find a Rational Rhapsody resource ID:

1. Add the following line to the [General] section of the rhapsody.ini file and save your
changes:

ShowActiveWindowHelpID=TRUE

This means that now when you press F1 to open the Rational Rhapsody help file, you will
see a window with a resource ID instead, as shown in the next step.

2. In Rational Rhapsody, press F1 for a GUID element that you plan to associate with a New
Term stereotype (for example, if your New Term stereotype is applicable to a class, the
Attributes tab of the Features window).
3. Add the resource ID number to your help map file. Each number must be on its own line.
The following figure shows the contents of a map file called myhelp.map. (Another
example of a help map file name: myhelp.txt.)

Note: For testing purposes as mentioned in Enabling access to your custom help file,
include the resource IDs shown in the following figure in your map file. You
can delete these IDs later.

Note: You might find it useful to add the name of the element next to the resource ID
number (for example, 161328 Attributes tab).

380 User Guide

 Profiles

4. If you plan to share the custom help file with team members, place the help map file in a
shared location on a network. You identify this file and its location in the
Model::Stereotype::CustomHelpMapFile property, as detailed in Enabling access to
your custom help file.

Note: When your map file is complete, to ensure that help topics appear instead of
resource ID numbers when you press F1, you can comment out the
ShowActiveWindowHelpID=TRUE line in the rhapsody.ini file (for example,
insert a semicolon or pound sign in front of the line) or you can delete the line.

Bookmarking your custom help file for a specific resource ID

When you press F1 to open your custom help file (when possible), it opens at the beginning of the
help file.

If for a particular resource ID (for example, the Tags tab of the Features window) you want your
custom help file to open to a specific spot in the custom help file, add a bookmark to that spot in
the help file. Use the standard HTML <a name> and </a> tags.

For example, the myhelp.htm help file has three sections labeled: Attributes, Ports, and Tags.
When you open the help file, you see the Attributes section first. If for the Tags tab, which is
resource ID 139316, you want to open the custom help file at the Tags section of the help file, you
would code it as follows in the myhelp.htm help file:
<a name=“139316”>Tags</a>
Then when you press F1 on the Tags tab, the custom help file opens at the Tags section of the help
file.

Rational Rhapsody 381

Model elements

Enabling access to your custom help file

To make these instructions easier to follow, they assume that there is a fictional project called
AutomobileProject that has a profile called Auto2009 with a New Term stereotype called
Stereotype_Auto2009. These profile and stereotype names are for illustrative purposes only; they
are not provided in Rational Rhapsody. (For information about creating a profile, see Creating a
customized profile. For information about stereotypes, see Stereotypes.)

Note
These instructions assume you have created your custom help file and your map file. See
About creating your custom help file and Creating your map file.

To enable access to your custom help file:

1. For the profile or its stereotype for the Rational Rhapsody project on which you want to
provide custom help, set the Model::Stereotype::CustomHelpURL and
CustomHelpMapFile properties as follows:

a. Open the Features window for the profile or its New Term stereotype. On the Rational
Rhapsody browser, double-click the profile name or stereotype name (for example,
profile Auto2009 or stereotype Stereotype_Auto2009).

b. On the Properties tab, select All from the View drop-down arrow (the label changes
to View All).

c. Locate Model::Stereotype::CustomHelpMapFile. Type the path to your help map

file.

Note: You can specify an environment variable as part of the URL (for example,
$DODAF_HLP_ROOT\dodaf_help.map).

382 User Guide

 Profiles

d. Locate Model::Stereotype::CustomHelpURL. Type the path to your help file. You

can specify an environment variable as part of the URL (for example,
$DODAF_HLP_ROOT\dodaf_help.htm).

e. Click OK.

2. Create an element using the New Term stereotype. Right-click a package in your project
and select Add New > Auto2009 >Stereotype_Auto2009. Notice that these choices are
located at the bottom of the pop-up menu.

3. Double-click the stereotype created in the previous step (for example,

stereotype_auto2009_0) and press F1. If you followed these steps and used the
resource IDs show in Creating your map file, your custom help file should open.

Testing the custom help file

Test your custom help file before releasing it to the users of the help file. You should be sure the
help file works as expected before releasing it. For example:

If the help file is to be accessed over a network, make sure it is accessible. You might want
to have someone else (besides the person who set it up) try to access the custom help file
from within Rational Rhapsody over the network before rolling out the feature to the rest
of your project team.
If you have set it so that your custom help opens at specific spots in the help file for
specific resource IDs, be sure to check these particular links. See Bookmarking your
custom help file for a specific resource ID.

Rational Rhapsody 383

Model elements

Using the custom help file

Once set up, anyone who uses the profile and elements with the New Term stereotype you set up
can use the F1 key to open the custom help file when and where it is possible. When you press F1,
Rational Rhapsody checks if there is a custom help file for the New Term stereotype associate with
the element.

If yes, Rational Rhapsody searches for the resource ID in your help map file and it opens
the custom help file.
If no, Rational Rhapsody opens its main help file.

Note
The GUI element must be applicable to the New Term stereotype for the Rational Rhapsody
profile for your custom help file to work.
For example, if the Auto2009 profile has a New Term stereotype called
Stereotype_Auto2009 and you add an element with this stereotype to a package called
Default, when you open the Features window for one of these stereotypes (for example,
stereotype_auto2009_0) and then you press F1, your custom help should open (assuming
you added the resource IDs for the tabs on this window to your help map file).

However, when you open the Features window for the package and you press F1, you open
the main Rational Rhapsody help file because this package is not associated with the New
Term stereotype call Stereotype_Auto2009.

384 User Guide

 Stereotypes

Stereotypes
Defined stereotypes are displayed in the browser. Stereotypes can be owned by both packages and
profiles.

To define a stereotype:

1. In the Rational Rhapsody browser, right-click the profile or package that owns the
stereotype and then select Add New > Stereotype. Rational Rhapsody creates a new
stereotype called stereotype_n under the Stereotypes category.

2. Enter a name for the new stereotype.

3. Double-click the new stereotype to open its Features window:

4. Select one or more metaclasses to which the stereotype is applicable to.

5. For profiles, if you are working in a domain with specialized terminology and notation,
select the New Term check box to create a new metaclass. Since a term is based on an
out-of-box metaclass, it functions in the same manner as its base metaclass. For more
information about new terms, see Special stereotypes.

6. Click OK.

7. Optionally, to set the formatting for the stereotype, right-click the new stereotype name in
the browser and select Format. Use the Format window to define the visual
characteristics for the stereotype.

Associating stereotypes with an element

You associate stereotypes with a model element using the Stereotype field of the Features window
for that element. The Stereotype field includes a list of all the stereotypes defined in the profiles
and packages that can extend the metaclass of that element. For example, if the element is a class,
the Stereotype list includes all the stereotypes in all the profiles and packages that extend that
class.

To associate stereotypes with an element:

Rational Rhapsody 385

Model elements

1. Open the Features window for the element.

2. Open the Stereotype list.

3. Use the check boxes to select the stereotypes you would like to apply to the element.

4. Click the arrow of the list to close the list.

5. Click Apply or OK.

Alternatively, you can select the stereotypes from a tree display, as follows:

1. Open the Features window for the element.

2. Click the Browse button next to the list.

3. Find the stereotypes you would like to apply. Use Ctrl and Shift to select more than one
stereotype.

4. Click OK to close the tree display.

5. Click Apply or OK.

Associate a stereotype with a new term element

Stereotypes can also be applied to elements that are based on “new term” stereotypes. In such
cases, the Stereotype list will not contain the stereotype on which the element is based, nor any
other “new term” stereotypes.

386 User Guide

 Stereotypes

Re-ordering stereotypes in a list

Stereotypes can be selected for display at the top of the list.

To change the order in which the selected stereotypes are displayed:

1. Click the Change Stereotype Order button , or right-click the stereotype list when it is
closed and select Edit Order.

2. When the list of selected stereotypes is displayed, use the up and down arrows to reorder
the list.

3. Click OK.

Associating a stereotype with a bitmap

Rational Rhapsody provides a set of predefined bitmaps in the directory <Rational
Rhapsody_installation>\Share\PredefinedPictures. You can associate these icons with
Rational Rhapsody stereotypes and classes.

1. Define a stereotype of your own or select one of the existing stereotypes.

2. Select this stereotype for a class.

3. Rename an existing .bmp file (or add a new file) in the PredefinedPictures directory so
it has the same name as the stereotype.

4. Drag-and-drop the class into an OMD.

5. Right-click the class and then select Display Options.

6. Under Show stereotype, select Icon; change Display name to Name only.

The bitmap is included in the class box.

Rational Rhapsody 387

Model elements

To change the bitmap background to transparent (so only the graphic itself is visible), set the
property General::Graphics::StereotypeBitmapTransparentColor to the RGB value of the
bitmap background.

The following figure shows bitmaps with transparent backgrounds.

Deleting stereotypes
1. Select the stereotype to delete.
2. Click the Delete button.

3. Click OK.

388 User Guide

 Stereotypes

Establishing stereotype inheritance

Stereotype inheritance allows you to extend existing stereotypes. Stereotypes can inherit from
from predefined stereotypes or from stereotypes that you have created.

The derived stereotype inherits the following characteristics from its base stereotype:

Applicability (which elements it can be applied to)

Properties (this includes locally-overridden properties)
Tags
While the initial values of properties for the derived stereotype are those that were inherited from
the base stereotype, the values can be overridden for the derived stereotype.

You can add tags to the derived stereotype, and add elements to the list of elements to which it can
be applied.

To establish stereotype inheritance, in the browser, right-click the stereotype that will be the
derived stereotype and select Add New > Super Stereotype

These steps can be repeated in order to create a stereotype that inherits from a number of other
stereotypes.

Special stereotypes
If a stereotype inherits from one of the “special” stereotypes, for example, usage or singleton, it
inherits the special meaning of the base stereotype.

If a stereotype inherits from a “new term” stereotype, then it is also a “new term” stereotype.
However, the “new term” status of the derived stereotype is removed if you do something that
contradicts this status, for example, using multiple inheritance such that the derived stereotype
ends up being applicable to more than one type of element.

Rational Rhapsody 389

Model elements

Use tags to add element information

Tags are used to add information to the model base specific to the domain or platform. You can
access them using the Tags tab of the Features window for Rational Rhapsody model elements.
The Tags tab shows the tag definitions and values associated with the given element. You can
create tags for a stereotype, metaclass, or individual element.

Defining a stereotype tag

When the Tags tab applies to a stereotype, it specifies the tag definition for all elements that use
the given stereotype. To define a new tag:

1. Create the profile to hold the tag if it does not already exist (see Creating a customized
profile).

2. If it does not already exist, define a stereotype for the profile and select <<New>> (see
Stereotypes). The Features window opens.

3. Select the Tags tab to display the window.

4. The Quick Add fields let you define the name for the tag and its default value quickly and
click Add.

5. You might want to enter a more detailed description of the tag in the area above the Quick
Add.

6. Click OK.

The new tag is added to the Tags tab. In addition, it is added to the browser.

This sample tag is listed as Profile::Component::<TagName> (in this example,

Avionics::Component::RiskFactor) because it was defined under the stereotype of the profile.
You would use this tag for components with the corresponding stereotype. For example, if you
have a component named System with the SafetyCritical stereotype, its Tag tab would
include the tag Avionics::SafetyCritical::RiskFactor.

Note
To create a new tag using the browser, right-click the stereotype and select Add New > Tag.
You can rename the tag if you want.

390 User Guide

 Use tags to add element information

Defining a global tag

When the Tags tab applies to a metaclass, it hosts all the tag definitions that are available to all
instances of a certain type (anywhere within the model), without the need to set a stereotype. When
you define a tag at the metaclass level, the Applicable to field is read-write so you can select the
appropriate element type from the list.

For example, you could create a new tag to specify prerequisite attributes for all primitive
operations in the project by selecting the Primitive Operation element from the Applicable to
list. This tag will be included automatically in the Tags tab of any primitive operation in the
project as <ProfileName>::<ElementType::<TagName>.

Defining a tag for an individual element

You can set a tag on an individual element to flag it in some way. When you create a tag for an
individual element, it is listed in the tab as LocalTags::Class::<TagName>. For example,
Local::Class::Review.

Adding a value to a tag

To add a value to a tag, click the Ellipsis button at the right end of the box next to the name of
the tag to open the internal text editor.

Rational Rhapsody 391

Model elements

Using the internal text editor

The Rational Rhapsody internal text editor is a simple text editor on which you can enter text or
code (depending on the functionality of the element you are working with). When using the
internal text editor is possible, Rational Rhapsody provides you with access to it. For example, to
open the internal text editor, you can click an Ellipsis button that displays on the Tags tab and the
Properties of the Features window.

392 User Guide

 Use tags to add element information

Deleting a tag
You can use the Rational Rhapsody browser or the Features window to delete a tag Select.

To delete a tag using the browser:

1. Right-click the tag on the browser and select Delete from Model.
2. Click Yes to confirm your requested action.

To delete a tag using the Features window:

1. Open the Features window for the element to which the tag belongs and select the Tags
tab.

2. Select the tag you want to delete and click the Delete button in the upper-right corner
of the tab.

Note
If you delete a tag definition in a stereotype, it is removed from the list of tags. However, if
the value for the tag has been overridden, that tag will not be removed.

Rational Rhapsody 393

Model elements

394 User Guide

 The Internal code editor

When you choose to edit code, Rational Rhapsody launches the internal code editor. This editor
has a wide range of features to assist with editing.

Unlike external editors, the Rational Rhapsody internal code editor provides dynamic model-code
associativity (DMCA). The DMCA feature of Rational Rhapsody enables you to edit code and
automatically roundtrip your changes back into the model. It also generates code if the model has
changed. If you use an external editor, DMCA will no longer be available.

Window properties
The Window Properties window enables you to customize the Rational Rhapsody internal code
editor window. Note that these window properties are completely separate from Rational
Rhapsody project properties. To open the window, right-click anywhere within the editor window
and select Properties.

Alternatively, press Alt+Enter on the keyboard. You can customize this shortcut using the
Keyboard tab on the Window Properties window. The window contains the following tabs:

Color/Font
Language/Tabs
Keyboard
Misc
The following sections describe how to use these tabs in detail.

The Color/Font tab

The internal code editor highlights syntax elements for easy editing. The default color settings
follow standard code editing conventions. Using the Color/Font tab, shown in the figure, you can
customize the colors and highlighting settings.

In addition to the default keywords (such as class and public), you can specify the additional
language-specific keywords to be color-coded by the Rational Rhapsody internal code editor by

Rational Rhapsody 395

The Internal code editor

setting the value of the property General::Model::AdditionalLanguageKeywords to the

comma-separated list of additional keywords you want to have color-coded.

Changing the default colors

The following table lists the default color and highlighting settings.

Item Foreground Background

Bookmarks Default Default
Comments Green Default
Keywords Blue Default
Left Margin White N/A
Numbers Teal Default
Operators Red Default
Scope Keywords Blue Default
Strings Purple Default
Text Black Default
Window Default N/A

To change the colors or highlighting:

1. Select the Color/Font tab on the Windows Properties window.

2. Select a code element from the Item list.

3. Choose a text color by selecting it in the Foreground list.

4. Choose a highlighting color by selecting it in the Background list. Note that background
highlighting is unavailable for all elements.

5. Click Apply to apply your changes and close the window.

396 User Guide

 Window properties

Changing the default font

By default, the internal code editor uses Courier New, regular, 10-point font to display text. It
supports any fixed-pitch font. When you change the font, it affects the appearance of all text in the
editor.

To change the font:

1. In the Font area of the Color/Font tab, click Change. The Font window opens, as shown
in the following figure.

2. As wanted, select new values for the Font, Font style, and Size fields. You can view the
effects of your changes in the Sample field.
3. Click OK twice.

Rational Rhapsody 397

The Internal code editor

The Language/Tabs tab

The Language/Tabs tab, shown in the following figure, controls the indentation and tab size used
by the editor.

The Language/Tabs tab contains the following fields:

Auto indentation style specifies whether lines are automatically indented according to
either the language scope or to the previous line in the file.

The possible values are as follows:

– Off turns off automatic indentation.
– Follow language scoping indents the code according to the language
specifications. This is the default setting.
– Copy from previous line uses the indentation established in the previous line
of code.
Tab specifies how many spaces make up a tab space.
If you want the tab character converted to spaces after insertion, check the Convert
tabs to spaces while typing box.

Note: Changes to tab size do not affect existing tab spacing. The new size applies to
tabs entered after the change is made.
Language specifies your programming language.

If you want any case errors corrected automatically for you, select the Fixup text case
while typing language keyword check box. For example, if this option is selected and

398 User Guide

 Window properties

you typed “WHile” as the keyword, the internal code editor automatically corrects the
case of the keyword to read “while.”

The Keyboard tab

The Keyboard tab, shown in the following figure, allows you to create shortcuts.

The edit commands are started using keyboard shortcut keys. Mapping edit commands to easy-to-
use and easy-to-remember keyboard shortcuts reduces the time and difficulty of editing text. Most
commands have been mapped to a default shortcut. You can modify all shortcuts from the
Keyboard tab of the Window Properties window.

Rational Rhapsody 399

The Internal code editor

Assigning custom keyboard mappings

The internal code editor provides customizable keyboard mappings so you can create your own
shortcuts for edit commands, or assign shortcuts to commands that do not have a default assigned.

To assign keyboard shortcuts:

1. On the Keyboard tab, select an edit command from the Command list.

If a shortcut has been assigned to this command, it is displayed in the

Key Assignments field.

A short description of the command is displayed in the Description field.

2. Click in the New Key Assignment box to activate it for editing.

3. Use the keyboard to type the shortcut key sequence. If you make a mistake, click Reset
and type the sequence again.

4. Click OK.

Default keyboard mappings

The following table lists the default edit commands that have been assigned shortcut keys.

Command Keystroke
BookmarkNext F2
BookmarkPrev Shift + F2
BookmarkToggle Ctrl + F2
CharLeft Left
CharLeftExtend Shift + Left
CharRight Right
CharRightExtend Shift + Right
Copy Ctrl + C
Copy Ctrl + Insert
Cut Shift + Delete
Cut Ctrl + X
CutSelection Ctrl + Alt + W
Delete Delete
DeleteBack Backspace

400 User Guide

 Window properties

Command Keystroke
DocumentEnd Ctrl + End
DocumentEndExtend Ctrl + Shift + End
DocumentStart Ctrl + Home
DocumentStartExtend Ctrl + Shift + Home
Find Alt + F3
Find Ctrl + F
FindNext F3
FindNextWord Ctrl + F3
FindPrev Shift + F3
FindPrevWord Ctrl + Shift + F3
FindReplace Ctrl + Alt + F3
GoToLine Ctrl + G
GoToMatchBrace Ctrl + ]
Home Home
HomeExtend Shift + Home
IndentSelection Tab
LineCut Ctrl + Y
LineDown Down
LineDownExtend Shift + Down
LineEnd End
LineEndExtend Shift + End
LineOpenAbove Ctrl + Shift + N
LineUp Up
LineUpExtend Shift + Up
LowercaseSelection Ctrl + U
PageDown Next
PageDownExtend Shift + Next
PageUp PRIOR
PageUpExtend Shift + Prior

Rational Rhapsody 401

The Internal code editor

Command Keystroke
Paste Ctrl + V
Paste Shift + Insert
Properties Alt + Enter
RecordMacro Ctrl + Shift + R
Redo Ctrl + A
SelectLine Ctrl + Alt + F8
SelectSwapAnchor Ctrl + Shift + X
SentenceCut Ctrl + Alt + K
SentenceLeft Ctrl + Alt + Left
SentenceRight Ctrl + Alt + Right
SetRepeatCount Ctrl + R
TabifySelection Ctrl + Shift + T
ToggleOvertype Insert
ToggleWhitespaceDisplay Ctrl + Alt + T
Undo Ctrl + Z
Undo Alt + Backspace
UnindentSelection Shift + Tab
UntabifySelection Ctrl + Shift + Space
UppercaseSelection Ctrl + Shift + U
WindowScrollDown Ctrl + Up
WindowScrollLeft Ctrl + Page Up
WindowScrollRight Ctrl + Page Down
WindowScrollUp Ctrl + Down
WordDeleteToEnd Ctrl + Delete
WordDeleteToStart Ctrl + Backspace
WordLeft Ctrl + Left
WordLeftExtend Ctrl + Shift + Left
WordRight Ctrl + Right
WordRightExtend Ctrl + Shift + Right

402 User Guide

 Window properties

The Misc tab

The Misc tab, shown in the following figure, controls numerous miscellaneous attributes for the
editor.

The following sections describe how to use some of the more interesting features available on the
Misc tab.

Using split views

You can split the editor window into up to four simultaneous views of one file, where each view
scrolls independently from the others. You can make changes in any view and all other views are
automatically updated.

To allow splitting of the screen into two horizontal panes, check the Allow Horizontal Splitting
box on the Misc tab. To allow splitting of the screen into two vertical panes, check the Allow
Vertical Splitting box.

To split the screen horizontally:

1. Click the horizontal splitter at the left end of the horizontal scroll bar (see the figure).

2. While holding down the mouse button, drag the splitter to the right until the new pane
displays.

Rational Rhapsody 403

The Internal code editor

To split the screen vertically:

1. Click the vertical splitter at the top of the vertical scroll bar.

2. While holding down the mouse button, drag the splitter downward until the new pane
displays.

Vertical splitter

Horizontal splitter

404 User Guide

 Mouse actions

Mouse actions
Use the mouse to select and edit text in the editor window. The following table lists the available
mouse actions.

Operation Mouse Action

Display menu Right-click.
Select entire line Click in the left margin next to the target line of text.
Select multiple lines Click in the left margin next to a line of text and drag the
mouse up or down
Select entire word Double-click anywhere in the word.
Move text (drag-and-drop) Select text; hold down the left mouse button while dragging
the selection to the new location.
Copy text (drag-and-drop) Select text; press Ctrl and hold down the left mouse button
while dragging the selection to the new location.

Using Undo and Redo

The internal code editor allows you to undo any number of operations, and redo the previous
operation.

The edit commands for undo and redo are as follows:

Undo use Alt+Backspace, or Ctrl+Z

Redo use Ctrl+A
For information on editing keyboard shortcuts for these commands, see Assigning custom
keyboard mappings.

You can set the maximum number of undo operations from the Window Properties window; the
default is to allow an unlimited number of undo operations.

To set the maximum number of undo actions:

1. On the Misc tab, in the Maximum Undoable Actions section, select Limited to.

2. In the adjacent box, type the maximum number of undo actions you want to allow.
3. Click OK.

Rational Rhapsody 405

The Internal code editor

Using the search feature of the internal code editor

The internal code editor contains a useful search feature that finds keywords within the current
file.

To search for a keyword:

1. Right-click and select Find.

2. In the What box, type the search string.

3. Select one of the following options:

Match whole word only finds instances where the search term is the whole word.
Match case finds matching instances that have the same case as the search term.
Direction choose Up to search text above the cursor position, or Down to search
text below the cursor position.
4. Click Find to find the next instance of the search term or click Mark All to place a
bookmark in the left margin next to all instances matching the search term.

406 User Guide

 Bookmarks

Bookmarks
The bookmark feature places a blue triangular marker in the left margin to identify a line of text.

To place a bookmark in the margin, use the BookmarkToggle edit command. The default shortcut
for BookmarkToggle is Ctrl+F2.

Repeat the BookmarkToggle command to remove the bookmark.

The bookmark commands are as follows:

BookmarkToggle use Ctrl+F2

BookmarkNext use F2
BookmarkPrev use Shift+F2
BookmarkJumpToFirst is unassigned
BookmarkJumpToLast is unassigned
BookmarkClearAll is unassigned
For instructions on editing the keyboard shortcuts for these commands, see Assigning custom
keyboard mappings.

Rational Rhapsody 407

The Internal code editor

Printing from the internal code editor

To print a file from the internal code editor:

1. Make sure that the editor window containing the file you want to print is the active
window in Rational Rhapsody.
2. From the Rational Rhapsody File menu, select Print.

3. In the Print window, select the printing options, then click Print.

408 User Guide

 Graphic editors

The Rational Rhapsody graphic editors for the different UML diagrams provide the tools needed to
create different views of a software model. Each graphic editor is described in detail in subsequent
sections of this guide. This section describes the menus and features that are common to all the
graphic editor.

Create new diagrams

You can use the Diagrams toolbar, Edit menu, Tools menu, or right-click menu commands in the
browser to create a new UML diagram.

Creating new statecharts

Statecharts describe the behavior of a particular class. They can be added only at the class level. A
class can have either a statechart or an activity diagram, but not both.

To create a new statechart, right-click a class in the Rational Rhapsody browser and select Add
New > Diagrams > Statechart. A new (blank) diagram is displayed in the drawing area.

Note
Add New > Diagrams is the default menu command structure in Rational Rhapsody. It can
be changed by users. This topic assumes that all defaults are in place.

Creating new activity diagrams

Activity diagrams describe the behavior of a particular class. They can be added only at the class
level. A class can have either a statechart or an activity diagram, but not both.

To create a new activity diagram, right-click a class in the Rational Rhapsody browser and select
Add New > Diagrams > Activity. A new (blank) diagram is displayed in the drawing area.

Note
Add New > Diagrams is the default menu command structure in Rational Rhapsody. It can
be changed by users. This topic assumes that all defaults are in place.

Rational Rhapsody 409

Graphic editors

Creating all other diagram types

The other diagrams can be grouped under the project or a package in the project hierarchy.

To create a new diagram other than a statechart or activity diagram:

1. Select the appropriate diagram type from Tools > Diagrams or click the appropriate
button on the Diagrams toolbar:

Object Model Diagram Component Diagram

Structure Diagram Deployment Diagram

Use Case Diagram Collaboration Diagram

Sequence Diagram Panel Diagram

2. From the Open Diagram window, select the project or a package where you would like to
add the diagram.

3. Click the New button. The New Diagram window opens.

4. Type a name for the new diagram in the Name box.

5. Depending on the diagram type, the New Diagram window can contain the following
options:

a. Populate Diagram, which automatically populates the diagram with existing model
elements. This option applies to object model, use case, and structure diagrams. For
more information, see Automatically populating a diagram.

b. Operation Mode specifies whether to create an analysis SD, which enables you to
draw message sequences without adding classes and operations to the model; or a
design SD, in which every message you create or rename is realized to an operation
in the static model. For more information, see Sequence diagrams.
6. Click OK. A new (blank) diagram is displayed in the drawing area.

410 User Guide

 Opening existing diagrams

Opening existing diagrams

To open an existing UML diagram, double-click the diagram in the Rational Rhapsody browser.
The diagram opens in the drawing area.

Alternatively, you can:

1. Click the appropriate button in the Diagrams toolbar to open the Open <Diagram Name>
window.
2. Depending on the type of diagram you want to open:

For statecharts and activity diagrams, select the diagram you want to open and
click OK.
For all other diagrams, select the diagram (if there are any) you want to open and
click Open.
As with other Rational Rhapsody elements, the Features window for the diagram enables you to
edit its features, including the name, stereotype, and description. For more information, see The
Features window.

Navigating forward from opened diagram to opened diagram

To go forward from open diagram to open diagram, choose Window > Forward.

In addition, you can go to a currently opened diagram by selecting it from the last section of the
Windows menu.

Navigating backwards from opened diagram to opened diagram

To go backwards from open diagram to open diagram, choose Window > Back.

In addition, you can go to a currently opened diagram by selecting it from the last section of the
Windows menu.

Rational Rhapsody 411

Graphic editors

Deleting diagrams
In most cases, you can delete existing UML diagrams only from the Rational Rhapsody browser.
However, you can delete statecharts and activity diagrams from both the browser and from the
Tools menu.

To delete an existing diagram:

1. Select the diagram from the browser.

2. Right-click and select Delete from Model, or press the Delete key.

3. Click Yes to confirm your action.

Automatically populating a diagram

When you create a new use case, object model, or structure diagram, you can use the Populate
Diagram feature to populate the diagram automatically with existing model elements. You can
select which model elements to add to the diagram. Rational Rhapsody automatically lays out the
elements in an orderly and easily comprehensible manner.

Relation type styles

Once the diagram has been created, you can edit it by adding or deleting elements to tailor it to
your needs. This feature is particularly useful for quickly creating diagrams after reverse
engineering or importing a model. When you automatically populate a new diagram, Rational
Rhapsody offers a choice of layout style. You can select either of these styles for any relation type:

Hierarchical
The elements are organized according to levels of inheritance, with lower levels inheriting
from upper levels. Each layer is organized to minimize the crossing and bending of
inheritance arrows and is individually centered in the diagram. You can choose this style
for any type of relation. If there are no classes or inheritance, the elements might appear
organized as layers, depending on the direction of the populated diagrams.

412 User Guide

 Automatically populating a diagram

Orthogonal
The entire drawing is made as compact as possible. Classes are placed to minimize the
intersection, length, and bending of relation arrows. You can use this style for any
relation, including inheritance relations.

Creating and populating a new diagram

To create a new, automatically populated diagram:

1. In the browser, right-click an existing use case, object model, or structure diagram
category where you want to create another of the same diagram and select Add New
<element type> (for example, Add New Object Model Diagram) to open the New
Diagram window.

2. Type the Name of the new element.

3. Select the Populate Diagram check box and click OK to open the Populate Diagram
window.

4. In the Create Contents Of Diagram Using group, indicate how you would like Rational
Rhapsody to create the contents of the diagram:

Relations Among Selected populates the diagram only with the selected elements
and the relations between them

Rational Rhapsody 413

Graphic editors

Relations From/To Selected populates the diagram with the selected elements,
their incoming and outgoing relations, and the model elements that complete
these relations
Relations From Selected populates the diagram with the selected elements, their
outgoing relations, and the model elements that complete the relations
Relations To Selected populates the diagram with the selected elements, their
incoming relations, and the model elements that complete the relations
5. In the Types Of Relations To Be Used group, select which types of relations you would
like Rational Rhapsody to use when creating the contents of the diagram:

OMDs and structure diagrams: Instance, Association/Aggregation, Inheritance,

Dependency, Link, and Anchor/Annotations
UCDs: Association, Generalization, and Dependency, and Anchor/
Annotations
6. In the Selection box, place a check mark next to each element you want to include in the
new diagram. To select a package without selecting the elements it contains, right-click
the package.

7. In the Preferred Layout Style group, select the type of layout you would like Rational
Rhapsody to use when creating the diagram. If you select None, Rational Rhapsody
automatically chooses the best layout style according to the type of relations you have
chosen to display.

8. Click OK. The new diagram displays in the drawing area with all of the selected elements
added. You can then begin to add information to the new diagram.

Note
When auto-populating a diagram, if you want Rational Rhapsody to populate each class so
it shows its attributes and operations, set the ObjectModelGE::Class::ShowAttributes
and ObjectModelGE::Class::ShowOperations properties to All in the scope of the
package or project.

414 User Guide

 Automatically populating a diagram

Automatically populating existing diagrams

Use the Populate Diagram window to automatically add elements and their relations to an existing
and already populated object model, use case, or structure diagram. To open this window, do any
of the following actions:

Right-click a blank spot on the diagram in its drawing area and select Populate or choose
Layout > Populate.
Right-click the diagram on the Rational Rhapsody browser and select Populate.
See the details for the Populate Diagram window in Creating and populating a new diagram.

Note
Rational Rhapsody does not change the location of already existing elements. it just adds
the new elements.

About reverse engineering object model diagrams

During reverse engineering with the Populate Diagrams check box selected, Rational Rhapsody
creates object model diagrams visualizing the elements added during reverse engineering. If you
run reverse engineering subsequently with the Merge existing package option, Rational
Rhapsody updates the visualized diagrams to show the new elements added and the dependencies
between the diagram elements.

Limitations of populating existing diagrams automatically

The Populate feature does not support the adding of ports, though existing ports on the diagram
will be preserved.

Rational Rhapsody 415

Graphic editors

Property settings for the diagram editor

The properties under General::Graphics control how features of the diagram editors operate.
The following table lists the available properties.

Property Description

AutoScrollMargin Controls how responsive the autoscrolling functionality is

ClassBoxFont Specifies the default font for new class names

CRTerminator Specifies how multiline fields in notes and statechart names

should interpret a carriage return (CR)
DeleteConfirmation Specifies whether confirmation is required before deleting a
graphical element from the model
ExportedDiagramScale Specifies how an exported diagram is scaled and whether it
can be split into separate pages for better readability
FixBoxToItsTextuals Specifies whether to resize boxes automatically to fit their text
content (such as names, attributes, or operations)
grid_color Specifies the default color used for the grid lines

grid_snap Specifies whether the Snap to Grid feature is available for

new diagrams, regardless of whether the grid is actually
displayed
grid_spacing_horizontal Specifies the spacing, in world coordinates, between grid
lines along the X-axis when the grid is available for diagrams
grid_spacing_vertical Specifies the spacing, in world coordinates, between grid
lines along the Y-axis when the grid is available for diagrams
HighlightSelection Specifies whether items should be highlighted when you
move the cursor over them in a diagram
LandScapeRotateOnExport Rotates an exported metafile so it can fit on a portrait page

MaintainWindowContent Specifies whether the viewport (the part of a diagram

displayed in the window) is kept for window resizing
operations when you change the zoom level, providing
additional space in the diagram in a smooth manner
MarkMisplacedElements Specifies whether misplaced elements are marked in a
special way. Previously, misplaced elements were shown with
a small X in the upper corner
MultiScaleByOne Specifies whether objects in the diagram keep the same
amount of space between them when you scale them
(Cleared)
PrintLayoutExportScale Specifies the factor by which the Windows metafile format
(WMF) files are scaled down in order to fit on one page
RepeatedDrawing Specifies whether repetitive drawing mode (stamp mode) is
available

416 User Guide

 Setting diagram fill color

Property Description

ShowEdgeTracking Specifies whether to show the “ghost” edges of a linked

element when you move it
ShowLabels Specifies whether to display labels instead of names in
diagrams
StereotypeBitmap Creates a “transparent” background for bitmaps associated
TransparentColor with stereotypes (so only the graphics are displayed in the
class box)
Tool_tips Enables the display of tooltips

You can set these properties by selecting File >Project Properties.

For detailed information on how the General::Graphics properties affect the drawing of your
model, see the definitions displayed in the Properties tab of the Features window.

Setting diagram fill color

To set the color of the diagram background:

1. Right-click in the diagram window and then select Diagram Fill Color.
2. Select a color.

Create elements
The diagram editors enable you to create a number of elements to enhance your model. To create
any kind of element, you must first select one of the drawing tools on it diagram editor toolbar.

When Rational Rhapsody is in drawing mode, the cursor includes a tooltip showing an icon of that
element. For example, the following cursor is displayed when you are drawing a class.

The items you can draw in the diagram editors fall into two main categories: boxes and lines. In
addition, Rational Rhapsody enables you to create freestyle shapes. The following sections
describe how to create these elements.

Rational Rhapsody 417

Graphic editors

Repetitive drawing mode

By default, each time you want to add an element to a diagram, you must first click the appropriate
icon in the Diagram Tools.

In some cases, however, you might want to add a number of elements of the same type. To
facilitate this, Rational Rhapsody includes a repetitive drawing mode.

To enter repetitive drawing mode, click the “stamp” icon in the Layout toolbar. Now, after
choosing a tool in the Diagram Tools, you will be able to continue drawing elements of that type
without selecting the tool again each time. If you choose a different tool from the toolbar, then
Rational Rhapsody will allow you to draw multiple elements of the newly selected type.

After you click the icon, Rational Rhapsody remains in repetitive drawing mode until you turn it
off. To turn off the repetitive mode, just click the "stamp" icon a second time.

Drawing boxes
Each editor contains tools to draw boxes. The following table lists the box elements available with
each editor.

Diagram Editor Box Elements

Object model Classes, packages, composite classes, objects,
files, actors, and annotations
Use case Use cases, actors, systems boundary boxes,
packages, and annotations
Component Components, files, folders, and annotations
Deployment Nodes, components, and annotations
Collaboration Objects, multi-objects, actors, and annotations
Statechart States and annotations
Activity Actions, subactivities, action blocks, object nodes,
swimlane frames, connectors, and annotations
Structure Composite classes, objects, and annotations

To draw a box:

1. Select a box tool.

2. Move the cursor to the drawing area, and do one of the following actions:

a. Quick-Draw where you can click once to draw a box with the default size, shape, and
name.

418 User Guide

 Create elements

b. Drag where to draw classes, simple classes, and packages, you click-and-drag to the
opposite corner and release. If you hold down the Shift key, you create a square box.

Note that the cursor changes to the icon of whatever you are drawing (class, object,
package, and so on).

3. When you complete the box, the element is given a default name. To rename it, click the
text to enable editing. Type the new name, then press Enter or click outside the box.

4. Click anywhere outside the box to start a new box, or click the Select tool to stop creating
boxes.

To add an existing box element to a diagram, you can simply drag-and-drop the element from the
browser to the drawing area.

Drawing arrows
Arrows connect boxes, representing the connections between different boxes in the diagram. For
example, associations and dependencies are two types of arrows that can be drawn in use case
diagrams.

You can draw arrows in the following ways:

Drag where you click inside the source box, drag, and release the mouse inside the
destination box.
Simple arrow clicks where you click inside the source box and click the border of the
destination box.
Multiple clicks where you click inside the source box, click any number of times to mark
the control points on the path of the arrow, and double-click inside the destination box.
You cannot add control points to a message arrow because it allows only two clicks.
Another point displays immediately to show where the next arrow will start.
Note that the cursor changes when you create arrows:

If you click a valid element for the destination of the arrow (for example, you are drawing
a activity flow and you click a class), the cursor changes to crosshairs in a small circle.
If you try to connect an arrow to an invalid element, Rational Rhapsody displays a “no
entry” symbol to show that you cannot connect the arrow to that element, as shown in the
following figure.

Rational Rhapsody 419

Graphic editors

Changing the line shape

Rational Rhapsody has three line shapes that you can use when you are drawing arrows in the
graphic editors. You can set a unique line shape for each line; the default line shape varies by
element.

The Edit menu contains the Line Shape option, which specifies your preferred line shape for the
specified arrow. You can also access the Line Shape option by right-clicking an arrow or line in a
diagram.

The possible values for the line shape are as follows:

Straight changes the line to a straight line.

Spline changes the line to a curved line.
Rectilinear changes the line to a group of line segments connected at right angles.
Re-Route removes excess control points to make the line more fluid.

Note
You can use the line_style property to change the line shape (straight, spline, rectilinear)
for a line type (for example, Link, Dependency, Activity Flow, Generalization) for a
diagram type (for example, Object Model, Activity, Statechart) by project. For example, in
your Handset project, you can use the ObjectModelGe::Depends::line_style property to
set Dependency lines for Object Model diagrams to be a spline shape. You should set this
property when you begin a project, as it takes effect going forward.
In addition, you can customize a line by adding/removing user-defined points to an arrow element.

To add points to an arrow element:

1. In the diagram, select the line you want to change.

2. Right-click and select User Points.

3. Depending on what you want to do:

To add a user-defined point, click Add. Note that the new point is added at the
location where you accessed the menu.
To remove a point, click Delete. Rational Rhapsody removes the point closest to
the location where you accessed the menu.
Note that you can reshape the line when the cursor changes to the icon shown in the following
figure:

Simply drag the line to reshape it.

420 User Guide

 Create elements

Naming boxes and arrows

Use either of the following methods to name boxes and arrows:

When you draw a box or a line, the cursor displays in the name field so you can edit it
immediately. Type a name and press Ctrl+Enter. Note that names, except for activity
flow labels, are limited to one line. To add an extra line to a activity flow label, press
Enter.
For activity flows in statecharts and activity diagrams, you can select the Name tool. The
cursor changes from an arrow to a pen. Click to select the name position, type a name, and
click outside the element to finish.
To edit an existing name, do one of the following actions:

Double-click the name to enable editing, and type a new name.

Open the Features window and edit the Name field on the General tab.

Note
If you rename a class box, you are renaming the class in the model.

Rational Rhapsody 421

Graphic editors

Draw freestyle shapes

Use the Free Shapes tool, which are displayed in its own section on the Diagram Tools panel, to
draw elements freehand in a diagram. To display or hide the Diagram Tools panel, choose View >
Toolbars > Drawing.

The Free Shapes toolbar provides tools that enable you to customize your diagrams using
freestyle shapes and graphic images.

The Free Shapes toolbar includes the following tools:

Tool Name Description

Line Draws a straight line between the selected endpoints.

Polyline Draws a polyline using multiple points.

Polygon Draws a polygon.

Rectangle Draws a rectangle.

Polycurve Draws a curve.

Closed Curve Draws a closed, curved shape within the bounds of the specified shape.

Ellipse Draws a circle or ellipse.

Text Draws free text.

Image Enables you to import an image into the diagram.

422 User Guide

 Create elements

The following figure shows examples of each freestyle shape.

The following sections describe how to draw these freestyle shapes.

Drawing lines and polylines

To draw a simple line:

1. Click the Line tool.

2. Click in the diagram and drag the cursor away from the endpoint to create the line. The
line is shown as a dashed line until you click to end the line.

If you click too early so only the square endpoint is displayed, click the endpoint and
redraw the line.

To draw a polyline using several points:

1. Click the Polyline tool.

2. Click to place the first endpoint.

3. Drag the cursor away from the endpoint, clicking once to place each subsequent point in
the polyline.

4. and once to place each point along the line.

5. Double-click to end the line.

Rational Rhapsody 423

Graphic editors

Drawing polygons
To draw a polygon:

1. Click the Polygon tool.

2. Click twice in the diagram to define two endpoints of a side, then drag and click to define
the polygon.

For example, to draw a triangle, simply define one side and drag the cursor to form the
triangle.

3. Click twice to complete the polygon.

Drawing rectangles
To draw a rectangle:

1. Click the Rectangle tool.

2. Click once in the diagram. By default, Rational Rhapsody draws a square with the
selection handles active.

3. Use the selection handles to create a rectangle.

424 User Guide

 Create elements

Drawing polycurves and closed polycurves

To create a curve:

1. Click the Polycurve tool.

2. In the diagram, click to define several points that define the curve. As you define points
(and, therefore, line segments), the resulting curve is drawn as a dashed line.

3. Double-click to create the curve.

Similarly, the Closed Polycurve tool creates a closed polycurve. As you define line segments, a
dashed line shows the shape of the resulting closed curve.

Rational Rhapsody 425

Graphic editors

Double-click to create the closed curve.

Drawing ellipses and circles

To draw an ellipse:

1. Click the Ellipse tool.

2. Click once in the diagram to place the left-most point of the ellipse.

3. Holding down the mouse button, drag the cursor to create the ellipse or circle.
4. Release the mouse button to complete the shape.

Drawing text
To create floating text:

1. Click the Text tool.

2. Click once in the diagram to place the text box.

3. Type the wanted text.

4. Press Enter for a new line; press Ctrl-Enter to place the text and dismiss the text box.

To change the text color, font, size, and so on, right-click the text and select Format. For more
information on changing text attributes, see Change the format of a single element.

426 User Guide

 Create elements

Adding images
To add an image to your diagram:

1. Click the Image tool. The Open window displays.

2. Navigate to the directory that contains the image you want to add to the diagram.

Note
The Rational Rhapsody distribution includes numerous bitmaps for common design
elements, such as CDs, timeouts, displays, and so on. These images are available in
Share\PredefinedPictures under the root installation directory.

3. Select the image to add.

4. Move the cursor to where you want to add the image, then click once to place it.

Deleting freestyle shapes

To delete a freestyle shape or graphic image:

1. In the diagram, select the shape to delete.

2. Click the Delete tool.

Rational Rhapsody 427

Graphic editors

Placing elements using the grid

You can display a grid and rulers to assist with positioning elements in all the graphic editors
except the sequence diagram editor.

To display the grid, click the Grid tool or select Layout > Grid > Show Grid.

Setting the grid properties

To set the attributes of the grid, select Layout > Grid > Grid Properties. The following figure
shows the resultant window.

You can set the following properties for the grid:

Grid Visible specifies whether the grid is displayed.

Grid Color specifies the color used for the grid dots. The default color is black.
Grid Spacing specifies the horizontal and vertical spacing of the grid points, in inches.

Snapping to the grid

To move an element you are drawing automatically to the closest grid points, select Layout >
Grid > Snap to Grid.

Displaying the rulers

To display rulers in the drawing area, click the Rulers tool or select Layout > Show Rulers. The
following figure shows an OMD with both the grid and rulers available.

428 User Guide

 Autoscroll

Autoscroll
By default, Rational Rhapsody automatically scrolls the diagram view while you are busy doing
another operation (such as moving an existing box element or drawing new edges by dragging)
that prevents you from doing the scrolling yourself. The autoscroll begins scrolling when the
mouse pointer enters the autoscroll margins, which are virtual margins that define a virtual region
around the drawing area (starting from the window frame and going X number of points into the
drawing area).

You can change the size of the autoscroll margins by setting the property
General::Graphics::AutoScrollMargin. This property defines the X number of points the
margins enter into the drawing area. If you specify a large number for this property, the margin
becomes bigger, thereby making the autoscroll more sensitive.

Set this property to 0 (no scroll region) to disable autoscrolling.

Rational Rhapsody 429

Graphic editors

Select elements
There are many ways Rational Rhapsody enables you to select elements in diagrams. You can
select an element using the mouse or using a variety of menu commands. Once you have selected
an element, you can edit it depending on what kind of element it is.

Selecting elements using the mouse

To select an element using the mouse:

1. Click the Select tool. When you move the mouse over the diagram, a standard mouse
pointer is displayed.

2. Click an element. When you select an element, all other elements are deselected.

a. To select a line or an arrow, click anywhere on it.

You can select the control point of an arrow only by clicking and dragging. For more
information, see Clicking-and-dragging.
b. To select a box, click anywhere inside it or on its border.

Selecting elements using the edit menu

Use Edit > Select to access the following commands for making selections:

Edit > Select > Select All selects all elements in the diagram.
Edit > Select > Select Next selects the element next to the current one, when two
elements are close together. This lets you easily navigate to each element in a diagram,
one at a time.
Edit > Select > Select by Area enables you to draw a selection box around a group of
elements within a container element (for example, classes in a package).
Edit > Select > Select Same Type selects all of the elements in the diagram that are of the
same type as the element currently selected. If more than one type of element is selected,
then all the elements of the different selected types will be selected.

430 User Guide

 Select elements

Selection handles
When an element is selected, selection handles are displayed around its edges. The following
diagrams selection handles on different elements.

Boxes have markers on each corner and usually on each side.

Arrows and lines have a marker on each end and on each control point on the line.

Non-rectangular elements, such as use cases or actors, and groups of elements have an invisible
bounding box with eight visible handles.

Note
The cursor changes depending on how the selected element will be changed. If the cursor is
displayed as a four-pointed arrow, the selected element can be moved to a new location. If
the cursor changes to a two-headed arrow, you can resize the element.

Selecting multiple elements

There are two ways to select more than one element:

Shift+Click
Clicking-and-dragging
Note that the last element selected in a multiple selection is distinguished by gray selection
handles. Gray handles indicate that the element is an anchor component. Rational Rhapsody uses
anchor components as a reference for alignment operations. If you want to use a different

Rational Rhapsody 431

Graphic editors

component as the anchor, hold the Ctrl key down and click another element within the selection.
Rational Rhapsody transfers the gray handles from the previous element to the selected element

For more information, see Arranging elements.

Shift+Click
1. Click the first element you want to select.

2. Press and hold down the Shift key, then click the rest of the elements you want to select.

Note
To remove an element from the selection group, press and hold down the Shift key and click
the element you want to remove from the selection.

Clicking-and-dragging
To make a multiple selection using the click-and-drag method:

1. Move the mouse pointer to a blank area of the diagram.

2. Press and hold down the left mouse button.

3. Drag to surround the area that contains the elements you want to select.

4. To add more elements to the selection, hold down the Shift key while you click-and-drag
again.

432 User Guide

 Edit elements

Edit elements
You can edit elements using the following methods:

Features window. For detailed information, see The Features window.

Right-click menu. When you select an element in a diagram and right-click, a menu lists
common operations you can perform on that element. Many of these options are element-
specific, but some of the common operations are as follows:
– Features or Features in New Window displays the Features window for the
specified element.
– Display Options enables you to specify how elements are displayed in the
diagram.
– Cut removes the element from the view and saves it to the clipboard.
– Copy saves a copy of the element to the clipboard and keeps it in the view.
– Copy with Model copies an element such that when it is pasted into a
diagram, a new element will be created in the model with the exact same
characteristics as the original element.
– Remove from View removes the specified element from the diagram but not
from the model.
– Delete from Model deletes the element from the model.
– Format changes the format used to draw the element (color, line style, and so
on). For more information, see Change the format of a single element.
– Line Shape enables you to change the shape of the line. For more
information, see Changing the line shape.
– User Points enables you to add additional points to, or delete points from, a
line element. This functionality enables you to customize the shape of the
line. For more information, see Changing the line shape. Element-specific
options are described with the individual elements.
Manipulating the element in the diagram. Use any of these methods to edit an element
in a diagram:
– Resize it.
– Move its control points.
– Move it to a new location.
– Copy it.
– Arrange it relative to one or more elements.
– Remove it from the view.
– Delete it from the model.
– Edit any text associated with it.

Rational Rhapsody 433

Graphic editors

Resizing elements
You can resize an element by stretching its sides. You can resize only one element at a time.

To resize an element:

1. Select the element.

2. Move the mouse pointer over one of its selection handles. When the mouse pointer is over
a selection handle, it changes to a double-pointed arrow. If you are editing a line, you can
also move the mouse pointer over a line segment.

3. Click-and-drag the mouse until the element is the wanted size and shape. If you want the
element to maintain its proportions as you resize it, hold down the Shift key before you
begin to click-and-drag.

If the box you are editing contains text, the text wraps to fit inside the boundaries of the new box.
If you are editing a box that is connected to other lines or contains other elements, the lines and
elements move and resize according to the box as you stretch it. If you hold down the Shift key,
you can stretch diagonally while maintaining the scale for the element.

To prevent elements from being resized when you resize their parent, press and hold the Alt key
while you click-and-drag with the mouse. Alternatively, you can select the menu item Edit >
Move/Stretch Without Contained before resizing the element.

To make Rational Rhapsody automatically enlarge the text box of a box element to fit the size of
an element name, select the Expand to fit text in the menu. Alternatively, select Layout >
Expand to fit text. Note that once you apply this feature to an element, it remains available until
you resize the element.

To use this functionality as the default behavior, set the property

General::Graphics::FitBoxToItsTextuals property to Checked.

Moving control points

If you have placed control points on arrows, you can select a control point and move it individually
to change the curve of the line. This is particularly effective within statecharts where activity flows
are rendered as spline curves.

See the description of the Reroute command in Changing the line shape for information on
removing extra control points.

434 User Guide

 Edit elements

Moving elements
You can move an element by clicking on it and dragging it to a new location. You can move
several elements simultaneously.

To move an element:

1. Select the element you want to move.

2. Move the mouse pointer over the element. The cursor changes to a four-pointed arrow,
which denotes a move operation.

3. Click-and-drag the element to a new location.

Note the following information:

To prevent elements from being moved when you move their parent boxes, hold down the
Alt key while you click-and-drag with the mouse. Alternatively, you can select the menu
item Edit > Move/Stretch Without Contained before moving the element.
If you hold down the Ctrl key when moving an element, a copy of the selected element is
created.
If you hold the Shift key down when moving an element, you can move it only
horizontally or vertically.

Maintain line shape when moving or stretching elements

When elements are stretched or moved, Rational Rhapsody maintains the relationship between
lines and boxes as much as possible to preserve diagram layout.

When moving or stretching more than one element at the same time, lines maintain their ratio to
the other elements. That is, the line stretches and moves along with the other elements. This can be
problematic for straight lines, which do not remain straight.

To maintain straight lines when moving or stretching boxes, move the boxes one at a time.

When moving or stretching only one box, lines that connect with vertical boundaries of the box
maintain their Y-coordinate, and lines that connect with horizontal boundaries of the box maintain
their X-coordinate. The coordinates change only when the box is moved to the extent that
maintaining those coordinates is impossible. This way, lines that are straight remain straight
whenever possible.

Rational Rhapsody 435

Graphic editors

Change the format of a single element

To edit the format of a single element in a diagram, right-click the element and select Format or
select Edit > Format. Alternatively, you can use the tools in the Format toolbar. For more
information, see Format text on diagrams.

The Format window lists the current line, fill, and font information for the selected element. The
following figure shows the default line attributes for a class.

Use the Line tab of the window to change the line color, style, or width or the lines used to draw
the element.

Note
Line widths 0 and 1 are the same; however, you can specify a new line type (dashed, dotted,
and so on) only for line width 0. Otherwise, the style options remain unavailable.

436 User Guide

 Edit elements

The Fill tab enables you to specify new fill attributes for the specified element, including the fill
and pattern colors, and the pattern style. The following figure shows the Fill tab for a class.

A preview of the pattern is displayed in the small box beside each pattern name.

For example, the following figure shows the preview of a fill color of green, a pattern color of
blue, with the Transparent pattern check box cleared.

Rational Rhapsody 437

Graphic editors

The Font tab enables you to specify new font attributes for the specified element, including the
font size and type, color, and whether the text should be in italics or bold, or underlined. The
following figure shows the Font tab for a class.

Note
These settings apply only to the specified element. Therefore, if you change the attributes
for an individual class, any new classes will use the default attributes. For information on
changing the attributes for a specific type of element (for example, all classes), see Change
the format of a single element.

438 User Guide

 Edit elements

Format text on diagrams

The Format toolbar provides tools that affect the display of text in your diagrams, such as font,
size, color, and so on. In addition, you can access these options by selecting Edit > Format >
Change. To display or hide this toolbar, choose View > Toolbars > Format.

The Format toolbar includes the following tools:

Tool Button Name Description

Font Type Specifies the font style (“type face”) used for text. Use the drop-down list to
select a different font.
Text Size Specifies the size used for text. Use the drop-down list to select a different size.

Italic Changes the selected text to italic font.

Bold Changes the selected text to boldface font.

Left Left-justifies the selected text.

This tool is available only in fields that support RTF, including the Description
for elements and annotation elements (comment, requirement, and constraint)
Center Centers the selected text.
This tool is available only in fields that support RTF, including the Description
for elements and annotation elements (comment, requirement, and constraint).
This tool is available only in fields that support RTF, including the Description
for elements and annotation elements (comment, requirement, and constraint)
Right Right-justifies the selected text.
This tool is available only in fields that support RTF, including the Description
for elements and annotation elements (comment, requirement, and constraint).
Bullet Creates a bulleted list.
This tool is available when you are editing the Description for an element.

Font Color Specifies the color to use for the text or label of the selected element. For
example, if you select a state and use this tool to change the color to red, the
name of the selected state is displayed in red.
This tool performs the same action as right-clicking an element and selecting
Format.
Line Color Specifies the color to use for the selected line element. For example, if you
select a state and use this tool to change the line color to blue, the text box for
the state will be displayed in blue.
This tool performs the same action as right-clicking an element and selecting
Format.

Rational Rhapsody 439

Graphic editors

Tool Button Name Description

Fill Color Specifies the color to use as fill color for the selected element. For example, if
you select a state and use this tool to change the color to yellow, the selected
state will be filled with yellow.
This tool performs the same action as right-clicking an element and selecting
Format.

Copying formatting from one element to another

Rational Rhapsody provides a Format Painter button to copy formatting from one element to
another element in the same diagram.

To copy formatting by using the Format Painter button:

1. In the diagram, click the element whose formatting you want to copy.
2. Click the Format Painter button in the Standard toolbar.

3. Click the element to which you would like to apply the copied formatting.

To copy formatting without having to click the Format Painter button each time:

1. In the diagram, click the element whose formatting you want to copy.

2. Click the Stamp Mode button in the Layout toolbar.

3. Click the Format Painter button

4. Click the elements to which you would like to apply the copied formatting.

Note
The Stamp Mode button is a toggle button. Rational Rhapsody will remain in “stamp mode”
until you click the button a second time.

440 User Guide

 Edit elements

Changing the format of a metaclass

In addition to changing the format of an individual element, you can change the format of an entire
metaclass. For example, you can specify styles for all classes, all actors, all associations, and so on.

To change the default settings for an entire metaclass:

1. Right-click the diagram and select Format to open the Format window.

Note: For diagrams only, the Format window has an Apply to modified elements
check box. For projects, packages, and stereotypes, there is an Apply to sub
elements check box instead.
2. In the Select Meta-class to format box, select the metaclass whose attributes you want to
change, then click the Format selected meta-class button.

Note: The Select Meta-class to format box displays only the metaclasses that are
relevant for the type of diagram.
3. Use the Format Properties window to select the new line, fill, and font attributes for the
metaclass and click OK. (For more information about using the Format Properties
window, see Change the format of a single element). The Preview box on the Format
window displays how the element will look in the diagram.

4. Click one of the available buttons on the Format window:

a. Cancel to discard all of your changes.

b. OK to save your changes to the specified metaclasses.

Note: If Apply to modified elements is available when you click OK, all the existing
elements in the selected scope (of the given metaclass) are changed to the
specified format (in addition to any elements that are created later). If Apply to
modified elements is unavailable, existing elements of the specified metaclass
that have individual overrides are not changed, but new elements will use the
new style by default.

For example, consider the case where all actors have white fill by default, but
actor A has blue fill with yellow stripes. If you change the default fill color for
all actors to be green, and Apply to modified elements is available, all the
actors will have white fill. However, if you clear this check box, all the actors
will have white fill, except for actor A, which will keep the blue fill and yellow
stripes. All subsequently created actors will use white fill.

Rational Rhapsody 441

Graphic editors

c. Reset to remove all user-specified formats for the specified element and “rolls back”
to the default values.

Note: If Apply to modified elements is available when you click Reset, Rational
Rhapsody displays a confirmation window that asks whether you want to reset
the default values for all of the modified subelements in the specified diagram
or project. Click Yes to remove all overrides; otherwise, click No and clear this
check box to reset specific metaclass styles.
d. Enforce to force a subelement to use the locally modified style. Note that this affects
only the styles that were explicitly specified; other formats remain unchanged. It is
similar to the behavior specified in Change the style scope.

Note: If Apply to modified elements is available when you click Enforce, Rational
Rhapsody displays a confirmation window that asks whether you want to force
the local style on all the elements in the specified diagram. Click Yes to remove
all overrides; otherwise, click No and disable this check box to reset specific
metaclass styles. Note that if you apply Enforce without enabling the Apply
check box, nothing is changed.
Use Edit > Format > Un-override to remove overrides on boxes and line elements in diagrams.

442 User Guide

 Edit elements

Change the style scope

Where you open the Format window affects the scope of the formatting style:

If you open the Format window from within a diagram, the format change applies only to
the metaclass in the current diagram.

For example, if you change the format of states in the Tester statechart so they are filled
with yellow, states in other statecharts will not be filled with yellow automatically.
If you open the Format window at the project level (select the project node in the browser,
right-click and select Format), the specified style is applied to that metaclass throughout
the entire model.
If you open the Format window by selecting an individual element in a diagram, the
specified style will be applied to that element only.
If you apply a style to an individual element and then copy it to a new diagram, it brings its style
with it. Consider the following scenario:

OMD_A uses purple fill for classes.

Class A in OMD_A has the individual fill style of blue cross-hatching.
Class B in OMD_A uses the default style for classes (purple fill).
OMD_B uses yellow fill for classes.
The following figure shows OMD_A.

Rational Rhapsody 443

Graphic editors

If you copy classes A and B into OMD_B, class A keeps its individual style, but class B now uses the
default local style (yellow fill). The following figure shows OMD_B.

To force the class to use the local style, click Enforce. In this example, class A is now forced to use
yellow as its fill color. Note that the cross-hatching is still used (because there is no setting for
cross-hatching in this OMD).

444 User Guide

 Edit elements

Making the format for an element the default formatting

After you have applied formatting to a diagram element, you can make the formatting for the
element the default formatting for new elements of this type.

To make the formatting of an element the default formatting for elements of that type:

1. Right-click the element in the diagram and select Make Default (or select the element and
choose Edit > Make Default). The Make Default window opens.

2. Select the characteristics to set as default. The available options are format, display
options, and size.

3. Select the level at which you would like to set the defaults, for example, diagram level or
package level.

Note
This option sets the default formatting for all new elements of the same type. For elements
that already exist in the diagram, the default formatting will be applied unless the elements
have been overridden. (This applies only to the formatting; the size of existing elements will
not be changed, nor will the display options.)

Copy an element
There are two different ways in which elements can be copied and pasted in a diagram:

Simple Copy where another representation of the element is created on the diagram
canvas.
Copy with Model where a new element is created in the model and pasted into the
diagram. The new model has the exact same characteristics as the original element.

Simple copy
You can copy an element in one of three ways:

Use the Copy and Paste commands in the Edit menu.

Use the Ctrl+Drag method.
Use the Layout > Replicate. Note that this applies to statecharts only.
To copy an element using the Ctrl+Drag method:

1. Select the element you want to copy.

2. Move the mouse pointer over the element.

Rational Rhapsody 445

Graphic editors

3. Press Ctrl. A small box with a plus sign in it is displayed below and to the right of the
pointer.

4. Click-and-drag the element. When you release the mouse button, a copy of the element
displays in the new location.

Note
In statecharts, copying creates new elements. In OMDs and UCDs, these methods copy
graphic elements but do not create new elements in the model.

Replicating
To copy using the Replicate command:

1. Select the element you want to copy.

2. Choose Layout > Replicate to open the Replicate window.

3. Enter the number of rows and columns you want the copied elements to use and the
spacing between them.

4. Click OK. Rational Rhapsody displays the replicated elements in the diagram.

446 User Guide

 Edit elements

Copying with model

This refers to the ability to copy a diagram element such that when it is pasted into a diagram, an
entirely new element is created, with all of the characteristics of the original element. For example,
if you use this option to copy and paste a class, a new class will be created in the model and it will
contain the same attributes and operations as the original class, the same associated diagrams (such
as a statechart), and so on.

To create a new model element based on an existing diagram element:

1. Select the element to be copied.

2. From the main menu, select Edit > Copy with Model.

3. Navigate to the diagram where you would like to paste the new object.

4. From the main menu, select Paste. The new element will appear in the diagram as well as
in the browser.

5. Rename the new item if wanted. The default name will be the name of the original element
with the string “_copy” appended to it.

Rational Rhapsody 447

Graphic editors

Arranging elements
In addition to the grid and ruler tools (described in Placing elements using the grid), the Layout
toolbar includes several tools that enable you to align elements in the drawing area.

To arrange elements:

1. Select View > Toolbars > Layout. The Layout toolbar is displayed.

Note: You can dock the toolbar by clicking-and-dragging it to a window edge.

2. The tools that enable you to arrange elements are unavailable until you select an elements
in the drawing area. In the diagram, select two or elements to arrange.
3. Select one of the layout tools. The elements are arranged according to the layout selected.

Note that the selection handles use different colors to show which element is used for the default
alignment and sizing (the last element selected).

Consider the two classes in the following figure.

448 User Guide

 Edit elements

The selection handles on class A are gray, which denotes that Rational Rhapsody will use the
values of class A for any alignments and sizing. Therefore, if you align the left sides of class A and
B, class A stays where it is and class B moves under it, as shown in the following figure.

Rational Rhapsody 449

Graphic editors

Layout toolbar
The Layout toolbar provides quick access to tools that help you with the layout of elements in
your diagram, including a grid, page breaks, rulers, and so on. To display or hide this toolbar,
choose View > Toolbars > Layout.

The Layout toolbar includes the following tools:

Tool
Name Description
Button
Toggle Grid Displays or hides the grid in the drawing area. This is equivalent to selecting
Layout > Grid > Show Grid.

Snap to Grid Automatically aligns new elements to the closest grid points. This is equivalent to
selecting Layout > Grid > Snap to Grid.

Toggle Rulers Displays or hides the rulers in the drawing area. This is equivalent to selecting
Layout > Show Rulers.

Toggle Page Displays or hides the page breaks in your diagram. This is equivalent to selecting
Breaks Layout > View Page Breaks.
Page boundaries are denoted by dashed lines.
Stamp Mode Turns repetitive drawing mode on or off.

Align Top Aligns the selected elements to the top of the element with the gray selection
handles. This is equivalent to selecting Layout > Align > Top.

Align Middle Aligns the selected elements to the middle (along the horizontal) of the element with
the gray selection handles. This is equivalent to selecting Layout > Align > Middle.

Align Bottom Aligns the selected elements to the bottom of the element with the gray selection
handles. This is equivalent to selecting Layout > Align > Bottom.

Align Left Aligns the selected elements to the left side of the element with the gray selection
handles. This is equivalent to selecting Layout > Align > Left.

Align Center Aligns the elements so they are aligned to the center, vertical line of the element with
the gray selection handles. This is equivalent to selecting Layout > Align > Center.

Align Right Aligns the selected elements to the right side of the element with the gray selection
handles. This is equivalent to selecting Layout > Align > Right.

Same width Resizes all the selected elements so they are the same width as the element with
the gray selection handles. This is equivalent to selecting Layout >
Make Same Size > Same Width.

450 User Guide

 Edit elements

Tool
Name Description
Button
Same height Resizes all the selected elements so they are the same height as the element with
the gray selection boxes. This is equivalent to selecting Layout >
Make Same Size > Same Height.
Same size Resizes all the selected elements so they are the same size as the element with the
gray selection boxes. This is equivalent to selecting Layout > Make Same Size >
Same Size.
Space across Spaces the selected elements so they are equidistant (across) from the element with
the gray selection handles. This is equivalent to selecting Layout > Space Evenly >
Space Across.
Space down Spaces the selected elements so they are equidistant (down) from the element with
the gray selection handles. This is equivalent to selecting Layout > Space Evenly >
Space Down.

Removing an element from the view

To remove an element from the view but not from the model:

1. Select the element to be removed.

2. Press the Delete key. The element is removed from the view.
Alternatively, right-click the element in the diagram and select Remove from View.

Deleting an element from the model

To delete an element from both the view and the model:

1. Select the element to be deleted.

2. Click the Delete tool or press Ctrl+Delete. The element is deleted from both the model
and the view.

Alternatively, right-click the element in the diagram and select Delete from Model.

Rational Rhapsody 451

Graphic editors

Editing text
To edit text:

1. Double-click any text to highlight it.

2. Edit the selection.

3. To add another line of text, press Enter; press Ctrl+Enter to end the edit.
Note that both the right mouse button and the Esc key cancel the edit.

Alternatively, for some features you can right-click the element in the drawing area and select Edit
Text.

452 User Guide

 Display compartments

Display compartments
One of the display options available for diagram elements is the display of contained items in
visual compartments. This option is available for the following items:

Classes
Objects
Files
For the above elements, the following items can be displayed in compartments where applicable:

Constraints
Tags (both local and on the element's stereotype)
Ports
Parts

Selecting items to display

To select the items that should be displayed:

1. In the Display Options window, click Compartments.

2. In the window that is displayed, use the arrows to select the items that should be
displayed, and the order in which they should be displayed.

3. Click OK.
In each compartment, individual items are displayed with an icon indicating the type of sub-
element. If the text is too long to display, an ellipsis is displayed. When this ellipsis is clicked, you
can view/edit the full text.

Note
For constraints, the content of the specification field is displayed.
The name of items can be edited in the compartments but items cannot be added or deleted.

It is not possible to modify the order in which individual items are displayed within each
compartment.

User-defined terms are displayed in the same compartment as the item on which they are based,
however, the icon indicates that this is a user-defined term.

Rational Rhapsody 453

Graphic editors

Note
While this feature allows you to display/hide attributes and operations, it does not replace
the attribute and operation tabs, which allow more precise display options, such as the
display of only a subset of defined attributes and operations.

Display stereotype of items in list

For elements listed in compartments, Rational Rhapsody provides the option of displaying the
name of stereotypes applied to the element alongside the name of the element.

To display elements' stereotypes in the compartment list, use these guidelines:

At the diagram level or higher, modify the property

General::Graphics::ShowStereotypes. The possible values for this property are
No, Prefix, Suffix.
The default setting for this property is Prefix.
This property applies to all of the compartments that can be displayed.

454 User Guide

 Zoom

Zoom
There are several zoom tools available on the Zoom toolbar, shown in the following figure.

Alternatively, you can choose View > Zoom/Pan > 50%, View > Zoom/Pan > 75%, View >
Zoom/Pan > 100%, or View > Zoom/Pan > 200%; or use the zoom options available in the menu
in the drawing area.

To prevent elements from being resized when you resize their parent (for example, classes
contained in a composite class), press and hold the Alt key while you click-and-drag with the
mouse.

Zoom toolbar
The Zoom toolbar contains the zoom tools you can use with all the different diagram types. These
tools are also available in View > Zoom or View > Zoom/Pan. To display or hide this toolbar,
choose View > Toolbars > Zoom.

The Zoom toolbar includes the following tools:

Tool
Name Description
Button
Zoom In Zooms in on a diagram. Click this button and click in a graphic editor window to
increase the view by 25%.

Zoom Out Zooms out on a diagram. Click this button and click in a graphic editor window to
decrease the view by 25%

Zoom to Select an element in a diagram and click this button to zoom into the selected
Selection section of the diagram.
Alternately, you can click Zoom In and hold down the left mouse button to draw a
selection box around the part of the diagram you want to zoom in on.
Pan Moves the diagram in the drawing area so you can see portions of the diagram that
do not fit in the current viewing area.

Zoom to Fit Resizes the active diagram to fit within the graphic editor window.

Rational Rhapsody 455

Graphic editors

Tool
Name Description
Button
Undo Zoom Reverses the last zoom action.

Scale The options on this drop-down list resize the active diagram scale by the selected
Percentage percentage.

Specification/ Displays either the specification or structured view of the active diagram.
Structured View

Zooming in and zooming out

To zoom in or out on a diagram:

1. Click the Zoom In or Zoom Out button (or choose View > Zoom > Zoom In or View >
Zoom > Zoom Out).

2. Move the cursor over the diagram. The cursor displays as a magnifying glass with either a
plus or minus sign in it.

3. Click the diagram to enlarge or shrink it by 25%, depending on which tool you selected.

There are two ways to zoom in on a portion of a diagram:

Click the Zoom In button, then hold down the left mouse button to draw a selection box
around the part of the diagram you want to zoom in on.
Select an element in the diagram, then click Zoom to Selection to enlarge the selected
element so it takes up the entire drawing area.

Note
You remain in zoom mode until you select another tool from the toolbar.

Refreshing the display

If at any time the screen becomes difficult to read, you can refresh it by pressing F5 or selecting
View > Refresh.

456 User Guide

 Zoom

Scaling a diagram
To scale a diagram to a certain percentage, use the drop-down scale box. You can set the diagram
scaling to a value between 10% and 500%.

Alternatively, select View > Zoom/Pan, then select the percentage used to scale the diagram.

To scale the diagram so the entire diagram in visible in the current window, click the Zoom to Fit
button (or View > Zoom/Pan > Zoom to Fit). When you click the button, the diagram is resized to
fit in the current window. This button performs the same command as View > Zoom to Fit.

Panning a diagram
Click the Pan button to move the diagram in the drawing area so you can see portions of the
diagram that do not fit in the current viewing area.

Undoing a zoom
To undo the last zoom, click the Undo Zoom button, or select View > Zoom/Pan > Undo Zoom/
Pan.

Specifying the specification or structured view

To show the specification or structured view of a diagram, click the Specification/Structured
View button.

For example, suppose you have a structured (composite) class A that contains the parts ObjectA
and ObjectB. The structured view looks like the following figure.

Rational Rhapsody 457

Graphic editors

The specification view looks like the following figure.

In addition to toggling between the two views, any new classes or objects created with the selected
mode will use that mode.

Note that if there is a mix of structured and specification elements, the button is disabled.

458 User Guide

 The Bird’s Eye (diagram navigator)

The Bird’s Eye (diagram navigator)

The Bird’s Eye (diagram navigator) provides a high-level view of the diagram that is currently
displayed. This can be very useful when dealing with very large diagrams, allowing you to view
specific areas of the diagram in the drawing area, while, at the same time, maintaining a view of
the diagram in its entirety.

The Bird’s Eye contains a depiction of the entire diagram being viewed, and a rectangle viewport
that indicates which portion of the diagram is currently visible in the drawing area.

Showing and hiding the Bird’s Eye window

To show/hide the Bird’s Eye window, do one of the following actions:

Choose View > Bird’s Eye.

Click the Bird’s Eye button on the Windows toolbar.

Use the keyboard shortcut, Alt+5.
Right-click the diagram in the drawing area, and then select Bird’s Eye.

Navigating to a specific area of a diagram

To use the Bird’s Eye to move to a specific area of a diagram, do one of the following actions:

Drag the viewport to the area you would like to view.

Click and draw a “new” viewport in the Bird’s Eye window over the area you would like
to view.

Using the Bird’s Eye to enlarge and shrink the visible area
To use the Bird’s Eye to enlarge/shrink the visible area of the diagram, drag an edge or corner of
the viewport to enlarge/shrink the viewport.

Enlarging the viewport has the same effect as zooming out in the drawing area. Shrinking the
viewport has the same effect as zooming in the drawing area.

Note
When you drag an edge of the viewport, the viewport size will always change in both
dimensions, maintaining the height/width ratio.

By default, the viewport will grow in the direction of the edge selected. If you hold down

Rational Rhapsody 459

Graphic editors

Ctrl while dragging, however, the viewport will grow in the direction of the opposite edge
as well in order to maintain the current center point of the diagram.

Scrolling and zooming in drawing area

If the scroll bars are used to change the visible area of the diagram in the drawing area, the
viewport will move accordingly in the Bird’s Eye window.

If the zoom level is changed in the drawing area, the size of the viewport will change accordingly
in the Bird’s Eye window.

Changing the appearance of the viewport

You can modify the appearance of the viewport rectangle in the Bird’s Eye window. Display
characteristics that can be modified include line color, line style, line width, fill color, and fill
pattern.

To display the viewport appearance window: Right-click anywhere in the Bird’s Eye window.

General characteristics of the Bird’s Eye window

The Bird’s Eye window is used only for changing the viewable area of a diagram. You
cannot modify any diagram elements in the Bird’s Eye window.
The size and position of the Bird’s Eye window is saved in the Rational Rhapsody
workspace.
The Bird’s Eye window can be resized, and it can float or be docked. The docking-related
options are accessed by right-clicking the borders of the window (but not the title bar).
The black dotted line in the Bird’s Eye window represents the diagram's drawing canvas.
When the canvas size is changed in the drawing area, this dotted line changes accordingly.
Depending on the size of the Bird’s Eye window, there might be some whitespace to the
right of and below the dotted line.

460 User Guide

 Complete relations

Complete relations
The Layout > Complete Relations menu completes relation lines in diagrams. For example, you
can define relations in the browser, draw the participating classes in an OMD, then select
Complete Relations to speed up the drawing of the relation lines.

Layout > Complete Relations > All completes all the relation lines
Layout > Complete Relations > Selected to All completes relation lines only for
relations originating in the selected classes
Layout > Complete Relations > Among Selected completes relation lines only for
relations existing between the selected classes

Rational Rhapsody 461

Graphic editors

Use IntelliVisor
The IntelliVisor feature offers intelligent suggestions based on what you are doing to reduce:

The number of steps required to complete a task

The amount of time spent changing between different views (browser, graphics editor,
code editor, and so on), giving more time to actually complete the task
The time spent in the “build and run” cycle because of fewer compilation problems
resulting from wrong type usage, misspellings, and so on
The suggestions offered by IntelliVisor depend on the current context. The context is a model
element (usually a class or a package) in which the IntelliVisor is activated. The IntelliVisor
contents is defined by the scope of the context. For example, the context can be class MyClass;
the list contents will be all the methods, attributes, and relations, including superclasses and
interfaces implemented by MyClass, and all the global methods defined in the package containing
the class.

The property IntelliVisor::General::ActivateOnGe specifies whether to enable IntelliVisor

in the Rational Rhapsody graphics editors. By default, IntelliVisor is available.

Activating IntelliVisor
When you press Ctrl+Space in the graphic editor, Rational Rhapsody displays a list box with
information from which to choose. You can navigate in this list box using either the arrow keys or
the mouse. When you select an item from the list of suggestions and press Enter, that text is
placed in the text box.

To dismiss the IntelliVisor list box, do one of the following actions:

Press one of the following keys:

– Esc
– Enter
Double-click the mouse button.
Change the window focus.
Press space/Alt.
Click outside of the text box.

462 User Guide

 Use IntelliVisor

IntelliVisor information
When you are using a graphics editor, IntelliVisor can simplify your tasks by offering shortcuts to
similar model elements.

For example, if you are drawing a class in an OMD or structure diagram and start IntelliVisor, the
list box contains the default name of the new class and all the classes that already exist in the
model. If you highlight one of the classes in the list, IntelliVisor displays summary information
available for that element, including:

Its type, name, and parent information

Its stereotype, if one exists
The first few lines of the description for the element, if one exists
The following figure shows information displayed by IntelliVisor.

To replace the new class with an existing class, simply highlight the class in the list box and double
left-click. IntelliVisor replaces the new class with the specified class.

In addition to classes, IntelliVisor can be opened in OMDs when you are drawing actors and
packages.

Rational Rhapsody 463

Graphic editors

Collaboration diagrams
If you open IntelliVisor on an object or multi-object, the list box contains all the classes in the
current project. For example:

If you apply a selection from the list, IntelliVisor replaces the part after the role name. For
example, AcmeTank:Tank will become AcmeTank:Jet if you select the Jet class in the list box.

In addition to classes, IntelliVisor can be started in collaboration diagrams when you are drawing
actors.

Component diagrams
If you start IntelliVisor for a component in a component diagram, the list box contains all the
components in the model. For example:

464 User Guide

 Use IntelliVisor

Deployment diagrams
If you start IntelliVisor on a node in a deployment diagram, the list box contains all the nodes
defined in the model. For example:

Note that you cannot activate component instances in IntelliVisor.

Sequence diagrams
If you start IntelliVisor within a sequence diagram, the list box contains the events, operations, and
triggered operations consumed by the target class. If there are base classes that consume events,
operations, and triggered operations, they are included in the list.

Note the following information:

If you select a constructor line, IntelliVisor displays the list of constructors.

The instance line should be associated with a part class, or the IntelliVisor list box will be
empty.

Rational Rhapsody 465

Graphic editors

Statecharts and activity diagrams

If you start IntelliVisor inside a activity flow trigger in a statechart or activity diagram before the “/
” or “[” symbol, the list box contains all the events that can be consumed by the class, as in this
example.

466 User Guide

 Use IntelliVisor

If you start IntelliVisor after the “/” or “[” symbol, the list box contains the default class content.
For example:

In addition, you can start IntelliVisor in activity diagrams to help you perform the following tasks:

Write initialization code for actions.

Edit the code for an activity.

Rational Rhapsody 467

Graphic editors

Use case diagrams

If you apply IntelliVisor on an actor, the list box contains all the actors defined in the project.

Similarly, if you start IntelliVisor on a use case, the list box contains all the use cases defined in the
project.

Structure diagrams
If you start IntelliVisor for an object in a structure diagram, the list box contains all the objects
defined in the project. For example:

Similarly, if you start IntelliVisor on a composite class, the list box contains all the composite
classes defined in the project.

468 User Guide

 Customizations for Rational Rhapsody

You can customize Rational Rhapsody in the following ways:

Add helper applications (also know as helpers). Helpers are custom programs that you
attach to Rational Rhapsody to extend its functionality. They can be either external
programs (executables) or Visual Basic for Applications (VBA) macros that typically use
the Rational Rhapsody COM API. They connect to a Rational Rhapsody object via the
GetObject() COM service. See Helpers.
Use Visual Basic for Applications (VBA), an OEM version of Microsoft Visual Basic to
develop automation and extensibility scripts that interact with the tool repository that
provides a full complement of user interface components (“forms”). See Visual Basic for
applications.
Create a customized profile to use in the models for your company. A customized profile
has the following advantages:
– Contains terminology specific to your company
– Forces adherence to special requirements or industry standards
– Can be reused in other models to simplify and standardize development efforts
See Creating a customized profile.

Add new element types to your models. See Adding new element types.
Create a customized diagram. See Creating a customized diagram.
Customize the Add New menu. See Customize the Add New menu.
Create a Rational Rhapsody plug-in. See Creating a Rational Rhapsody plug-in.

Rational Rhapsody 469

Customizations for Rational Rhapsody

Helpers
Helpers are custom programs that you attach to Rational Rhapsody to extend its functionality.
They can be either external programs (executables) or Visual Basic for Applications (VBA)
macros that typically use the Rational Rhapsody COM API. They connect to a Rational Rhapsody
object via the GetObject() COM service.

You can add your helper to the Rational Rhapsody Tools menu. To open, the Helpers window,
open a Rational Rhapsody project and choose Tools > Customize.

The following tools are available on the Helpers window:

Click the New icon to create a new helper menu item.

Click the Delete icon to delete a helper menu item.

Click the Move Up icon to move up the helper item on the Rational Rhapsody Tools
menu.

Click the Move Down icon to move down the helper item on the Rational Rhapsody
Tools menu.

Use the following boxes on the Helpers window to identify and apply your helper application:.

Command Browse to the path to your helper application.

Arguments Optionally, add a binding for a parameter that resolves to a run-time instance.
Initial directory For an external program helper only, browse to the path of the default directory
for the helper application.
Applicable to From the drop-down list, select the model elements to associate with the
helper.
Project type From the drop-down list, select one or more profiles (for example, FunctionalC,
DoDAF, SysML) to which the helper applies.
Helper trigger From the drop-down list, select the action that will trigger this helper.

At the bottom of the window, identify if your helper application is an external program helper or
VBA macro helper.

470 User Guide

 Helpers

List of helper triggers

The following helper triggers are available:

After Project New

After Project Open
Before Project Save
After Project Save
Before Check Model
Before Code Generation
After Roundtrip
After Change To
After Add Element

Rational Rhapsody 471

Customizations for Rational Rhapsody

Creating a link to a helper application

To create a link to a helper:

1. Open a Rational Rhapsody project and choose Tools > Customize to open the Helpers
window.

2. Click the New icon to add a blank line for a new menu item in the Menu content box.

3. In the blank field, type the name of the new menu item (for example, My New Command).

To specify a submenu structure, enter the menu text with a backward slash ( \ ), for
example, External\My New Command1.

Note that you can have more than one item in your submenu structure. You can
create another link to a helper and specify it as, for example, External\My New
Command2.
To make a shortcut key, add an ampersand character before a letter in the name.
For example, &My makes the letter M a menu shortcut. You can press Alt+M to
open this particular helper application once it has been created. Be sure to not use
a letter that is already used as a shortcut key on the Tools menu or the pop-up
menu for the associated model element.
4. Specify the applicable helper parameters:

In the Command box, enter the command that the menu item should start, such as
E:\mks\mksnt\cp.exe or click its Ellipsis button to browse to the location
of the application.
Optionally, in the Arguments box, enter any arguments for the command.
Optionally, in the Initial Directory box, enter an initial default directory for the
program. This applies only to external programs.
In the Applicable To list, specify which model elements to associate with the new
command.

If you do not specify a value for this field, the menu command for this helper
application can be added to the Tools menu depending on what you do in Step 6.
In the Project Type list, select a project profile, as defined in Creating a project.

If leave this box blank, it uses as the default the profile of the current project you
have opened.
In the Helper Trigger list, select the actions that triggers the new command.

472 User Guide

 Helpers

5. Specify the helper type:

Select the External program radio button if the new command is an external
program, such as Microsoft Notepad.

Select the Wait for completion check box if you want the external program to
complete running before you can continue to work in Rational Rhapsody.
Select the VBA macro radio button if the new command is a VBA macro and is
defined in the <Project>.vba file. See Adding a VBA macro.
6. Depending on what you decided for the Applicable To list:

If you did not specify an applicable element for the command, verify that the
Show in Tools menu check box is selected. This means the new menu command
for your link to a helper application displays on the Tools menu. If you clear this
check box, there is no menu command for it on the Tools menu, though the link to
the helper application still works once the trigger for this command is started.
If you specified an applicable element for the command, verify that the Show in
Pop-up menu check box is selected. This means the new command displays in
the menu for the specified model element. If you clear this check box, there is no
menu command for it on the pop-up menu for the specified model element,
though the link to the helper application still works once this command is started.
7. Click OK to apply your changes and close the window. (You can click the Apply button if
you want to save your changes but keep the window open to continue working with it.)

Once you save and close the Helpers window, the link to the helper application you just
created is immediately available if the current project is within the parameters that you set
for the link. For example, if the Rational Rhapsody project you currently have open uses
the FunctionalC profile and you created the My New Command helper application for this
profile, then this link to the helper application is immediately available. However, if you
specified the DoDAF profile (as selected in the Project Type drop-down list) for the My
New Command link, then it will not work in your current project.

Rational Rhapsody 473

Customizations for Rational Rhapsody

Examples of helper application menu commands

If you did not specify an applicable model element and you selected the Show in Tools menu
check box on the Helpers window, as shown in the following figure on the left, your helper
application menu command is added to the Tools menu, as shown on the right.

474 User Guide

 Helpers

If you specified an applicable model element for your command and you selected the Show in
pop-up menu check box on the Helpers window, as shown in the following figure on the left, you
can right-click either the model element on the Rational Rhapsody browser to access the menu
command for the helper application, as shown on the right, or the applicable element in a graphical
editor. Note that the command now does not show on the Tools menu.

Rational Rhapsody 475

Customizations for Rational Rhapsody

Using a .hep file to link to helper applications

You can use a .hep file to group links to helper applications that help achieve the purpose of a
Rational Rhapsody profile. Helper applications are custom programs created by you or a
third-party that you can link to within the Rational Rhapsody product. Helper applications add
functionality that a profile might not have, such as the ability to query a model or write to a
project. For more information about profiles, see Profiles.

Using a .hep file is ideal for teams where all members should use the same helper applications.
When your project profile and its corresponding .hep file are loaded by reference, when your team
members update, they get the latest versions of these files. A .hep file is considered part of a
profile and is treated as such.

To see sample .hep files, you can look at the ones provided with the Rational Rhapsody product for
certain profiles, such as AUTOSAR, DoDAF, MODAF, NetCentric, and Harmony. For example,
<Rational Rhapsody installation path>\Share\Profiles\DoDAF contains DoDAF.sbs (the
profile file) and DoDAF.hep. Java users might want to look at the sample .hep files for the
AUTOSAR and NetCentric profiles.

If sharing links to helper applications is not an issue, or perhaps it is company policy that everyone
have access to the same helper applications for all Rational Rhapsody projects, then adding links
to helper application in the rhapsody.ini file might suffice.

However, you might find using a .hep file more convenient:

Easier maintenance. The rhapsody.ini file is typically overwritten when you get a new
version of Rational Rhapsody. Since the name of a .hep file must correspond with the
name of a profile, there is less likelihood of the .hep file being overwritten.
Less clutter on your list of menu commands. The links to help applications can appear as
menu commands on the Tools menu. Typically, many people work on various projects
that might use different models (and profiles) and different helper applications. Using the
rhapsody.ini file to store all your links to helper applications might cause clutter on
your list of menu commands. You can use a different .hep file for each profile so that you
only see the helpers needed for your project.

476 User Guide

 Helpers

To use a .hep file to link to helper applications:

Note
The method described here is the typical way to link to a helper application. If you prefer to
not use Tools > Customize (which opens the Helpers window), you should review the
options on the Helpers window to familiarize yourself with the available options and their
syntax. For example, look at the Helper Trigger box for the list of available triggers and
notice how they are spelled out and capitalized. For more information about the Helpers
window, see Helpers.
1. Open Rational Rhapsody and choose Tools > Customize to create one or more links to
helper applications. See Creating a link to a helper application.

The code for your links is added to the rhapsody.ini file.

2. Close Rational Rhapsody.

3. Open the rhapsody.ini file and from the [Helpers] section of the file, copy the code for
your help application. The following example show helper application code that was
added to the rhapsody.ini file:
[Helpers]
...
name30=AutoCommand45
command30=C:\WINDOWS\NOTEPAD.EXE
arguments30=
initialDir30=C:\WINDOWS
JavaMainClass30=
JavaClassPath30=
JavaLibPath30=
isVisible30=1
isMacro30=0
isPlugin30=0
isSynced30=0
UsingJava30=0
applicableTo30=
applicableToProfile30=Auto2009
helperTriggers30=After Project Open
isPluginCommand30=0

Note: Each section of link code starts with name##.

4. Open your .hep file and paste the code for the link to a helper application (what you copied
in the previous step).

Your .hep file must have the same name as the name of the profile for your Rational
Rhapsody project. For example, if the profile for your Rational Rhapsody project is called
Auto2009, your .hep file must be called Auto2009.hep. In addition, both the profile and
the .hep file must reside in the same folder.
5. In the rhapsody.ini file, delete the code that you copied in Step 3. The code to link to a
helper application should only reside in the .hep file when you are using a .hep file.

Rational Rhapsody 477

Customizations for Rational Rhapsody

6. Open Rational Rhapsody and open your model.

7. Load the applicable profile by reference. This is the profile that has the corresponding .hep
file; see Step 4.

8. Test to make sure your link to a helper application works as expected.

For example, if a link is suppose to open a helper application after you open a model
(helperTriggers30=After Project Open, as shown in the sample code in Step 3),
make sure that happens.

Note
You can use the General::Model::HelpersFile property to associate a .hep file with a
model.

Note that if you specify a .hep file using this property, Rational Rhapsody will not recognize
the helper applications defined in the profile-specific .hep file if one is provided for the
profile you are using.

Modifying a link to a helper application

To modify a link to a helper application:

1. With a project open in Rational Rhapsody, choose Tools > Customize to open the Helpers
window.

2. If you want to edit the name of the helper application, double-click it in the Menu content
box and make your changes.

3. Make other changes on the Helpers window as you want. For an explanation of the
controls on the Helpers window, see Creating a link to a helper application.

Modifying a .hep file

To modify a link to a .hep file by modifying the applicable .hep file:

1. Close the Rational Rhapsody model.

2. Open the .hep file in a text editor (such as Microsoft Notepad) and make your changes.

3. Save your changes to the .hep file.

4. Open the Rational Rhapsody model.

5. Test to make sure your changes work as expected.

478 User Guide

 Helpers

Adding a VBA macro

The Helpers window can also be used to add a VBA macro. To add a VBA macro:

1. With a project open in Rational Rhapsody, choose Tools > Customize to open the Helpers
window.

2. Click the New icon to add a blank line for a new VBA macro menu command in the
Menu content box.

3. In the blank field, type the name of the new menu item (for example, My VBA Command).

4. Select the VBA macro radio button as the helper type. The Helpers window lists
VBA-specific options.

5. Specify the applicable helper parameters:

In the Module box, enter the name of the VBA module.

In the Macro name box, enter the name of the VBA macro.
In the Applicable To list, specify which model elements to associate with the new
command.

If you do not specify a value for this field, the menu command for this link to a
helper application might be added to the Tools menu depending on what you do
in Step 6.
In the Project Type list, select a project profile, as defined in Creating a project.

If leave this box blank, it uses as the default the profile of the current project you
have opened.
In the Helper Trigger list, select the actions that triggers the new command.
6. Depending on what you decided for the Applicable To list:

If you did not specify an applicable model element for the command, verify that
the Show in Tools menu check box is selected. This means the new menu
command for your link to a helper application displays on the Tools menu. If you
clear this check box, there is no menu command for it on the Tools menu, though
the link to the helper application still works once the command is started.
If you specified an applicable model element for the command, verify that the
Show in Tools menu check box is selected. This means the new command
displays in the menu for the specified model element. If you clear this check box,
there is no menu command for it on the pop-up menu for the specified model
element, though the link to the helper application still works once the command is
started.

For examples, see Examples of helper application menu commands.

Rational Rhapsody 479

Customizations for Rational Rhapsody

7. Click OK.
The helper application you just created is immediately available if the current project is
within the parameters that you set for the helper application. For example, if the Rational
Rhapsody project you currently have open uses the FunctionalC profile and you created
the My New Command helper application for this profile, then this helper application is
immediately available. However, if you specified the DoDAF profile (as selected in the
Project Type list) for the My New Command helper application, then it will not work in
your current project.

Note
It is your responsibility to add code to your VBA macro to verify that the selected object is
actually the core object for your command. The COM command to get the selected element
is getSelectedElement().

480 User Guide

 Visual Basic for applications

Visual Basic for applications

Visual Basic for Applications (VBA), an OEM version of Microsoft Visual Basic, is integrated as
an automation engine into the Microsoft Office family and for use in all Microsoft tools. It
provides a complete application development environment based on Visual Basic.

With VBA, you can develop automation and extensibility scripts that interact with the tool
repository that provides a full complement of user interface components (“forms”). There is
virtually no limit to application extensibility that can be achieved using VBA. Conceptually, it
would be possible to completely transform the hosting application into another application using
VBA extensibility.

VBA and Rational Rhapsody

The basic interaction between VBA and Rational Rhapsody is facilitated through the Rational
Rhapsody COM API, similar to the way Visual Basic interacts with Rhapsody using API external
programs. Rhapsody exports a set of COM interfaces that represent its metamodel objects, as well
as its application operational functions. Through the COM interfaces, a VBA macro can easily
access all the Rhapsody objects and manipulate them.

The VBA project file

A VBA project is a file container for other files and components that you use in Visual Basic to
build an application. After all the components have been assembled in a project and code written
for it, you can compile the project into an executable file.

Each Rational Rhapsody project is associated with a single VBA project that contains all VBA
artifacts (scripts, forms, and so on) that you created within the Rational Rhapsody project. This
project file has the name <project name>.vba and is located in the same directory as the
Rational Rhapsody project file (<project>.rpy). This binary file will be loaded (if present) with
the Rational Rhapsody project and saved when you select Save from Rational Rhapsody or the
VBA IDE.

VBA versus VB programs

The major difference between writing API external programs with VB and writing VBA scripts
inside Rational Rhapsody is the availability of the Rational Rhapsody root object, known as the
Rational Rhapsody application. External VB programs need to create a Rhapsody application
object; Rhapsody VBA scripts have direct access to the already existing application object.

Whether accessed by VB or VBA programs, operations of the Application object are identical
in function. To the VBA user, however, it looks like all the methods of the root object are local
methods in the VBA context. For example, traversing the Rhapsody model always starts with

Rational Rhapsody 481

Customizations for Rational Rhapsody

accessing the project object. The following example shows a VBA script that displays the name of
the project:
Dim a as Object
Set a = getProject
MsgBox a.name

Note: The method getProject is a function of the root object.

Writing VBA macros

Rhapsody allows you to program a script (or “macro”) in the Microsoft Visual Basic programming
language to perform automated activity.

To write a Visual Basic macro for Rational Rhapsody:

1. Launch the VBA IDE in one of the following ways:

a. Select View > Toolbars > VBA and then select the first icon from the left to launch
the VBA IDE.

b. Select Tools > VBA and then select Visual Basic Editor from the popup menu.

2. Edit the Visual Basic project file, <project>.vba, to implement different macros. Once
you are finished editing, exit the VBA IDE and save the Rhapsody project. The VBA
project is automatically saved whenever the Rhapsody project is saved.

Running and sharing macros

Later, you can run a Rhapsody VBA macro from the Macros window or as a helper in the Tools
menu. In addition, macros can be shared with other users through the macro exporting and
importing process.

API methods for a VBA macro

Note that helper applications might not close the current document. This means that you should
not use the following API methods in a VBA macro that you specify as a helper:

Method Interface Object

quit IRPApplication
openProject IRPApplication
close IRPProject

482 User Guide

 Visual Basic for applications

Creating and editing macros

You can create a new macro or edit an existing macro in two ways:

Using the VBA Macros window in Rational Rhapsody

– To create a macro, type in a new name in the Macro Name field, then select
Create.
Note: Since VBA macros are contained in modules, you must first create a module
before creating your first macro. If you have not yet created a module, the
Create button is disabled. Modules cannot be created from the Macros
window. You must open the VBA IDE to do so.
– To edit a macro, highlight the existing macro in the Macro window, then
select Edit.
Launch the VBA IDE and create and edit new macros there. There, you can do one of the
following actions:
– Select Tools > VBA > Macros to open the Macros window.

Start typing the new macro with the line Sub xxxx(), where xxxx is the name
of the new macro. The last line of the macro must be “End Sub.”
– Find an existing macro by expanding the Modules folder of the Project
window and double-clicking the appropriate module. You can scroll the code
window to the existing macro or select it in the right pull-down above the
code window.
This is a simple VBA macro:
Sub GetNameOfProject()
Dim a as Object
Set a = getProject
MsgBox a.name
End Sub
Once you have finished typing this macro, return to the Rhapsody window and run the new macro
through the Macros window. You see a small message box with the name of the currently loaded
project.

Rational Rhapsody 483

Customizations for Rational Rhapsody

VBA Macros window

The VBA Macros window enables you to run, edit, or delete a macro.

To open the Macros window, use the VBA Toolbar shortcut or select Tools > VBA > Macros. The
following figure shows the Macros window. The window contains the following fields:

Macro Name contains the name of the highlighted macro in the Macro Box field. This
field is blank if there are no macros in the Macro Box.
Macro Box lists the available macros in the VBA project selected in the Macros In box.
Macros In lists the available VBA projects that contain macros.
The window contains the following buttons:

Run runs the selected macro.

To run a macro, highlight a macro in the Macro box, then click Run.

Step Into highlights the first line of the macro and places the Current Execution Line
Indicator.
Edit opens the Code window with the selected macro visible so you can modify your
macro.
To edit a macro, highlight the macro in the Macro box, then click Edit.

Create opens a module in the Code window so you can create a new macro.
To create a macro, type in a new name in the Macro Name field, then click Create.

Note: Since VBA macros are contained in modules, you must first create a module
before creating your first macro. If you have not yet created a module, the
Create button is disabled. Modules cannot be created from the Macros
window. You must open the VBA IDE to do so.
Delete removes the selected macro from your project.
To delete a macro, highlight a macro in the Macro box, then click Delete.

Saving your macros

Rational Rhapsody VBA macros are saved automatically with your Rhapsody project. When you
load the project again, the macros you have created for it will be available.

484 User Guide

 Visual Basic for applications

Exporting and importing VBA macros

To export the VBA macros for a module from the VBA IDE:

1. Select a module from the modules tree.

2. From the VBA IDE, select File > Export File.

3. In the Export Files window, browse to the correct location and enter the name of the
receiving file.

4. Select OK to dismiss the Export Files window.

Rational Rhapsody also enables you to import an existing module or form to the project.

To import VBA macros:

1. From the VBA IDE, select File > Import File. The Import Files window is displayed.

2. Browse to the correct location and select the file to import.

A copy of the file is added to the project and the original file is left intact. If you import a form or
module with the same name as an existing form or module, the new form or module file is added
with a number appended to its name.

Rational Rhapsody 485

Customizations for Rational Rhapsody

Creating a customized profile

To create a customized profile:

1. Create a project that you want to use as the basis for your customized profile. If you select
a Rational Rhapsody profile for this project, the characteristics of that profile are going to
be used as the default values.

2. Right-click the top-level project name (for example, Dishwasher) and select Add New >
Profile, and then enter a name for your profile. Notice that Rational Rhapsody creates a
Profiles category and places your profile within it.

Alternatively, if you have a package that you want to change to be a profile, right-click the
package and select Change to > Profile. For more information, see Converting packages
and profiles.

3. Enter any information about the profile that you want your team members to know about
on the Description tab.

4. Optionally, you can do the following actions:

a. Define global tags for your profile: Open the Features window for the profile (for
example, double-click the profile name) and define tags on the Tags tab.

b. Add a stereotype to your profile: On the General tab of the Features window for your
profile, select <<New>> from the Stereotype box. A Features window opens for the
stereotype on which you can name the stereotype. Notice that by default Rational
Rhapsody sets that this stereotype is applicable to a profile. Notice also that you can
make it a New Term stereotype. For more information about creating stereotypes, see
Stereotypes.

After you close the Features window for the stereotype and return to the Features
window for the profile, notice that the stereotype you just created is showing in the
Stereotype box of the General tab for the profile.

486 User Guide

 Creating a customized profile

Creating a new stereotype for the new profile

To create a stereotype, but not immediately apply it to a profile:

1. Right-click your profile and select Add New > Stereotype. Remember to select the
metaclass to which the stereotype applies.

Later you can apply the stereotype to a profile by opening the Features window for the
profile and selecting the particular stereotype on the General box.

2. Once Rational Rhapsody creates the Stereotype category on the browser, you can
right-click the name and select Add New Stereotype to create more stereotypes.

Re-using your customized profile

Since a profile is a package, it can be used in other projects to save time and support corporate
standards easily.

To re-use your customized profile:

1. Make a corresponding text file for your custom profile and give it the same name but with
the .txt extension. Add a description for the profile. The content of the text files displays
on the description area of the New Project window.
For example, if your customized profile is MyProfile.sbs, create a MyProfile.txt file.

2. Copy the .sbs file for the profile and the corresponding .txt file to <Rational Rhapsody
installation path>\Share\Profiles\<customized profiles foldername>. For
example, you would place a copy of the MyProfile.sbs and MyProfile.txt files in, for
example, C:\Rhapsody\Share\Profiles\CustomProfiles.

If you have packages under your profile, choose to not make each package its own
separate unit so that you can keep the entire profile in a single .sbs file (clear the Store in
separate file for those package).

3. When you want to use a custom profile with a new project, you can select the profile from
the Project Type drop-down list of the New Project window.

Rational Rhapsody 487

Customizations for Rational Rhapsody

You can also share your custom profiles through the following methods:

Save the customized profile (package) and make it available through a CM system or in a
shared area where other developers can access it.
Add a custom profile to an existing project with File > Add Profile to Model. Select the
customized profile (an .sbs file) from its stored location.
Note that with this method certain elements might not be brought over to your new project
is they are not associated specifically with the profile/project.
When multiple projects are displayed in a browser, a developer can drag and drop the
customized profile from one project to a different open project to re-use it. For more
information about this process, see the instructions in Copy and reference elements among
projects.

Note
You can set your customized profile to be automatically added to a new project either as a
copy or a reference using the AutoCopied or AutoReferences properties. For more
information, see Profile properties.

488 User Guide

 Adding new element types

Adding new element types

The stereotype mechanism is used for introducing such new elements. In general, stereotypes are
used to add new information to a model element. However, if you define a new stereotype and
specify that it should be a New Term, it becomes a new element that can be used in models.

To add a new type of element:

1. Create a new stereotype. See Stereotypes.

2. Open the Features window for the new stereotype and select one item from the Applicable
To list. This item is the element on which the new element is based.

3. Select New Term.

4. Click OK.

Once the new term is created, it is possible to add elements of this type via the context menu in the
browser.

New terms and their properties

For each new term introduced, properties can be used to specify characteristics such as the type of
icon to use for the term in the browser or the icon to be used in the Diagram Tools. For each of the
available properties, if no value is provided, Rational Rhapsody uses the value provided for the
element on which the new term is based.

Note
Since stereotypes can be added to profiles and packages, the new terms created can be
shared across models.

Rational Rhapsody 489

Customizations for Rational Rhapsody

Availability of out-of-the-box model elements

In addition to allowing the introduction of new element types, Rational Rhapsody allows you to
hide any out-of-the-box element types that your users do not need.

The availability of metaclasses is determined by the General::Model::AvailableMetaclasses

property. This property takes a comma-separated list of strings.

Note
To keep all of the out-of-the box metaclasses, leave this property blank.
To limit the availability of certain metaclasses, use this property to indicate the metaclasses that
you would like to have available. The strings to use to represent the different metaclasses are as
follows

ActivityDiagram
ActivityFlow
Actor
Argument
Association
AssociationEnd
Attribute
Block
Class
ClassifierRole
CollaborationDiagram
CombinedFragment
Comment
Component
ComponentDiagram
ComponentInstance
Configuration
Connector
Constraint
Constructor

490 User Guide

 Adding new element types

ControlledFile
Dependency
DeploymentDiagram
Destructor
EnumerationLiteral
Event
ExecutionOccurrence
File
Flow
FlowItem
Folder
Generalization
HyperLink
InteractionOccurrence
InteractionOperand
Link
Message
Module
Node
Object
ObjectModelDiagram
Package
Pin
Port
PrimitiveOperation
Profile
Project
Reception
ReferenceActivity
Requirement
SequenceDiagram
State

Rational Rhapsody 491

Customizations for Rational Rhapsody

Statechart
Stereotype
StructureDiagram
Swimlane
SysMLPort
Tag
Transition
TriggeredOperation
Type
UseCase
UseCaseDiagram

492 User Guide

 Creating a customized diagram

Creating a customized diagram

In addition to allowing you to filter out certain out-of-the-box diagrams that you do not want to
see, Rational Rhapsody allows you to add customized diagrams. This is done by creating a new
diagram type on the basis of one of the Rational Rhapsody basic diagrams and adding customized
diagram elements, if needed, to the list of elements available for the new type of diagram.

Note
The procedure for adding customized diagrams with custom elements can only be used for
adding new types of diagrams. It is not possible to add new diagram element types to the
standard Rational Rhapsody diagrams.
Customized diagrams can be added at the individual model level, or they can be added to profiles
so that they can be used with other models as well.

To create your customized diagram:

1. In the browser window, add your customized profile. See Creating a customized profile.
(While the customized diagram can be added for the current model only, usually
developers and designers want to add it to a profile so that it can be reused.)

2. Select the name of the new profile in the browser, and use the context menu to create a
new stereotype. See Stereotypes.

3. Open the Features window for the new stereotype you created, and set the following
values:

a. On the General tab, from the Applicable to list select the type of diagram that should
serve as the base diagram for the new diagram type you are creating. In addition,
select the New Term check box.

b. On the Properties tab, enter the required values for the following properties:

– Model::Stereotype::DrawingToolIcon supplies the name of the .ico file

that should be used as the icon for the new diagram type in the Diagrams
toolbar.
– Model::Stereotype::BrowserIcon supplies the name of the .ico file that
should be uses as the icon to represent the new diagram type in the browser.

If no value is provided for DrawingToolIcon, the file name entered for

BrowserIcon are used in the Diagrams toolbar as well. If values are not
provided for either of these properties, then the icon for the base diagram is
displayed both in the browser and in the Diagrams toolbar.
– Model::Stereotype::DrawingToolbar is a comma-separated list
representing the elements that should be included in the Diagram Tools for
this type of diagram, for example, RpyDefault,RpySeparator,Actor,Block.

Rational Rhapsody 493

Customizations for Rational Rhapsody

RpyDefault represents all the elements included in the Diagram Tools of the
base diagram. If this property is left empty, only the tools from the base
diagram is displayed. The toolbar can contain any drawable elements
supported by the base diagram, and any new elements based on these
elements.

Adding customized diagrams to the diagrams toolbar

Once you have created a customized diagram type, it is included automatically in the Tools menu.
You also have the option of including an icon for the new diagram type in the Diagrams toolbar.
To add the new type of diagram to the Diagrams toolbar:

1. Open the Features window for the profile to which you added the new type of diagram.
2. On the Properties tab, modify the value of the General::Model::DiagramsToolbar
property to include the name of the new diagram type in the comma-separated list, for
example, OV-1, RpySeparator,RpyDefault. (If this property is left empty, the toolbar
includes only the default icons.)
The strings to use in this list are given in Diagram types.

Creating a customized diagram element

After a new diagram type have been defined, you can define new drawing elements that can be
included in the Diagram Tools for the new type of diagram. This is done by basing the new
element on one of the elements that is available by default in the diagram type that served as the
base for the new customized diagram, as follows:

1. Select the name of the relevant profile in the browser, and use the context menu to create a
new stereotype.
2. Open the Features window for the new stereotype you created, and set the following
values:

a. On the General tab, from the Applicable to list select the type of drawing element
that should serve as the base element for the new diagram element type you are
creating. Also, select the New Term check box.

b. On the Properties tab, provide values for the following properties:

– Model::Stereotype::DrawingToolIcon provides the name of the .ico file

that should be used as the icon for the new drawing element when it is
included in a Diagram Tools.
– Model::Stereotype::DrawingToolTip provides the text that should be
displayed as a tool tip for the icon in the Diagram Tools.

494 User Guide

 Creating a customized diagram

– Model::Stereotype::DrawingShape where if you would like to customize,

to a certain degree, the appearance of the new element that you created, you
can select one of the options provided for this property, for example, you can
create a new element based on Class, but specify that the object have
"rounded corners" when displayed on a diagram.
– Model::Stereotype::AlternativeDrawingTool where in certain cases, a
number of different out-of-the-box drawing elements are based on the same
metaclass, for example, both Class and Composite Class are based on a
metaclass called Class. In these cases, in addition to specifying the base
metaclass in the Applicable to box, you must provide the name of the wanted
base element in the property. This property does not have to be provided for
the "default" element for the metaclass. Using our example above, if you were
basing the new element on the Class element, there would be no need to
provide a value for this property.
The complete list of diagram elements and corresponding metaclasses is provided in Diagram
elements. This table also indicates the “default” diagram element for each metaclass.

Rational Rhapsody 495

Customizations for Rational Rhapsody

Adding customized diagram elements

After customized diagram elements have been created, they can be added to one or more of the
customized diagram types you have created:

1. In the browser, under Stereotypes, select the customized diagram to which you would like
to add the custom element, and open its Features window.

2. On the Properties tab, for the Model::Stereotype::DrawingToolbar property, add the

name of the new element type you created to the comma-separated list representing the
elements that should be included in the Diagram Tools for this type of diagram.

Then names of the elements that can be used for this list are given in Diagram elements.

Note
After defining new diagrams or diagram elements, you need to reload the model to have
access to the new items or, alternatively, choose View > Refresh New Terms.

Diagram types
The following list contains the strings to use for the General::Model::DiagramsToolbar
property:

ActivityDiagram
CollaborationDiagram
ComponentDiagram
DeploymentDiagram
ObjectModelDiagram
SequenceDiagram
Statechart
StructureDiagram
UseCaseDiagram
RpyDefault
RpySeparator

496 User Guide

 Creating a customized diagram

Diagram elements
The following elements can be customized for the specified diagrams, as described in Adding
customized diagram elements.

AlternativeDrawingTool
Element Name Metaclass Name
Property Required
Object Model Diagram
Object Object
Class Class
Composite Class Class Yes
Package Package
Port Port
Inheritance Generalization
Association AssociationEnd
Directed Association AssociationEnd Yes
Composition AssociationEnd Yes
Aggregation AssociationEnd Yes
Link Link
Dependency Dependency
Flow Flow
Actor Actor
Sequence Diagram
InstanceLine ClassifierRole Yes
EnvironmentLine ClassifierRole Yes
Message Message
ReplyMessage Message Yes
CreateMessage Message Yes
DestroyMessage Message Yes
TimeoutMessage Message Yes
CancelTimeoutMessage Message Yes
TimeIntervalMessage Message Yes
PartitionLine ClassifierRole Yes
Condition Mark Message Yes
ExecutionOccurrence ExecutionOccurrence

Rational Rhapsody 497

Customizations for Rational Rhapsody

AlternativeDrawingTool
Element Name Metaclass Name
Property Required
InteractionOccurrence InteractionOccurrence
InteractionOperatorCombinedFra CombinedFragment
gment
InteractionOperand InteractionOperand
Use Case Diagram
UseCase UseCase
Actor Actor
Package Package
Association AssociationEnd
Generalization Generalization
Dependency Dependency
System Border ClassifierRole Yes
Flow Flow
Collaboration Diagram
Classifier Role ClassifierRole Yes
Multi Object ClassifierRole Yes
Classifier Actor ClassifierRole Yes
AssociationRole ClassifierRole Yes
Link Message Message Yes
Reverse Link Message Message Yes
Dependency Dependency
Structure Diagram
Composite Class Class Yes
Object Object
Block Block
Port Port
Link Link
Dependency Dependency
Flow Flow
Deployment Diagram
Node Node
Component Component

498 User Guide

 Creating a customized diagram

AlternativeDrawingTool
Element Name Metaclass Name
Property Required
Dependency Dependency
Flow Flow
Component Diagram
Component Component
File File (Component)
Folder Folder
Dependency Dependency
Interface Class Yes
Realization Cannot use as base element
Flow Flow
Statechart
State State
ActivityFlow Transition
InitialFlow DefaultTransition
AndLine Cannot use as base element
StateChartConditionConnector Connector Yes
HistoryConnector Connector Yes
TerminationConnector Connector Yes
JunctionConnector Connector Yes
DiagramConnector Connector Yes
StubConnector Connector Yes
JoinConnector Connector Yes
ForkConnector Connector Yes
TransitionLabel Transition Yes
TerminationState State Yes
Dependency Dependency
Activity Diagram
Action State Yes
ActionBlock State Yes
SubActivityState State Yes
ObjectNode State Yes

Rational Rhapsody 499

Customizations for Rational Rhapsody

AlternativeDrawingTool
Element Name Metaclass Name
Property Required
ReferenceActivity ReferenceActivity
Transition Transition
DefaultTransition DefaultTransition
LoopTransition Transition Yes
ActivityChartConditionConnector Connector Yes
TerminationState Connector Yes
JunctionConnector Connector Yes
DiagramConnector Connector Yes
JoinConnector Connector Yes
ForkConnector Connector Yes
TransitionLabel Transition Yes
Swimlane Frame Swimlane Yes
SwimlaneDivider Swimlane Yes
Dependency Dependency
ActivityPin Connector Yes
ActivityParameter Connector Yes

500 User Guide

 Customize the Add New menu

Customize the Add New menu

Rational Rhapsody offers you a number of ways to customize the Add New menu. This menu is
the one you see when you right-click an item in the Rational Rhapsody browser and select Add
New.

Re-organizing the common list section of the Add New menu

The top section of the Add New menu is known as the common list portion of this menu. The
General::Model::CommonList property controls which elements appear in this section, when
applicable.

To re-organize the common list section of the Add New Menu for a project:

1. Open your project in Rational Rhapsody.

2. Open the Features window. Choose File > Project Properties.

3. Locate General::Model::CommonList and change the values for this property.

4. Click OK.

5. To confirm your change, right-click a package in your project and select Add New. Only
those values you entered in CommonList appear, as long as they are applicable to your
project.
Note the following information:

Whatever element that is removed from the common list group of the Add New menu will
appear in the middle section of the Add New menu if it is relevant for your project. The
element must appear somewhere if it is a valid element for your project.
If the AddNewMenuStructure property is in use, that property overrides the properties
mentioned here. See Customizing the Add New menu completely.
If you want to use this Add New menu customization in other projects (without having to
manually change the property for each of them), see Re-using property changes to the Add
New menu.
See also Re-organizing the bottom section of the Add New menu.

Rational Rhapsody 501

Customizations for Rational Rhapsody

Re-organizing the bottom section of the Add New menu

You can re-organize the groups and their elements located at the bottom section of the Add New
menu. If there are groups or elements that you do not use by project, you can re-organize this
section of the Add New menu to list only those groups/elements that you want to use.

To re-organize the Add New menu, use the following properties in General::Model:

SubmenuList
Submenu1List
Submenu1Name
Submenu2List
Submenu2Name
Submenu3List
Submenu3Name
Submenu4List
Submenu4Name
A definition for each property displays on the Properties tab of the Features window.

The following example shows how you could re-organize the groups and their elements located at
the bottom of the Add New menu. In this scenario, you want to show only the activity diagram,
flowchart, and panel diagram in the Diagrams group of the Add New menu for your project. In
addition, you want to remove the Table\Matrix group.

Note: This example assumes that the properties mentioned in this topic have the
default values.
1. Open your project in Rational Rhapsody.

2. Open the Features window. Choose File > Project Properties.

3. Locate General::Model::Submenu1List.
Note that this property is associated with the Submenu1Name property, which has a value
of Diagrams.

4. Type ActivityDiagram, Flowchart, and PanelDiagram as the values for Submenu1List.

5. Click OK.
6. Locate General::Model::SubmenuList.
This property controls what submenu groups appear at the bottom of the Add New menu.

7. Delete Submenu3 from the values entered for the SubmenuList property.
Submenu3 specifies the Table\Matrix submenu that can appear on the Add New menu.

502 User Guide

 Customize the Add New menu

8. To confirm your changes, right-click a package in your project and select Add New. Only
those diagram types you entered in Submenu1List appear, as long as they are applicable
to your project. Meaning, if a flowchart is not applicable to your project, that choice will
not appear on the Add New menu under the Diagrams category. In addition, the
Table\Matrix submenu item no longer displays on the Add New menu.

Note the following information:

Whatever element that is removed from a group from the bottom of the Add New menu
will appear in the middle section of the Add New menu if it is relevant for your project.
When you remove a group, all the elements in that group will appear in the middle section
of the Add New menu. Elements must appear somewhere if they are valid elements for
your project.
The Submenu1List and Submenu1Name properties are also used by Tools > Diagrams.
When you make a change to Submenu1List, to have it take effect on Tools > Diagrams,
you must save your project, close it, and then open it again. In addition, if you delete the
Submenu1 value from the SubmenuList property, all the Rational Rhapsody diagram
choices will appear in the Tools menu, instead of under Tools > Diagrams (after you save
your project and open it again).
If the AddNewMenuStructure property is in use, that property overrides the properties
mentioned in this topic. See Customizing the Add New menu completely.
If you want to use this Add New menu customization in other projects (without having to
manually change the properties for each of them), see Re-using property changes to the
Add New menu.
See also Re-organizing the common list section of the Add New menu.

Rational Rhapsody 503

Customizations for Rational Rhapsody

Customizing the Add New menu completely

You can completely customize the choices that appear in the Add New menu to focus on a
particular process or need.

To completely customize the choices that appear in the Add New menu for your project:

1. Open your project in Rational Rhapsody.

2. Open the Features window. Choose File > Project Properties.

3. Locate the General::Model::AddNewMenuStructure property and set the elements you

want to appear for the Add New menu.
The property definition on the Properties tab of the Features window provides you with
more information on how to use this property.
4. Click OK.

5. To confirm your changes, right-click a package in your project and select Add New. Only
those elements you entered in AddNewMenuStructure appear on the Add New menu, as
long as they are applicable to your project.

Note: If you want to use this Add New menu customization in other projects (without
having to manually change the property for each of them), see Re-using
property changes to the Add New menu.

Compare with Re-organizing the common list section of the Add New menu and Re-organizing the
bottom section of the Add New menu.

504 User Guide

 Customize the Add New menu

Re-using property changes to the Add New menu

You can automatically apply the changes you make to the properties that control the Add New
menu for use in other projects by setting your applicable property changes in a New Term
stereotype that is associated with a particular profile that is set to be applicable to a project, and
then applying the profile to your other projects.

To apply property changes to the Add New menu to other projects:

1. Create a new project (name it, for example, Project2).

2. Create a profile for the project. Right-click the project name, select Add New > Profile
and name it (for example, MyProfile).

3. Create a stereotype for the profile. Right-click the profile and select Add New >
Stereotype and name it the same as the profile.
If you name this stereotype the same name as the profile (in this example, MyProfile,
Rational Rhapsody will auto-apply the stereotype to a project when you use the profile.

4. Open the Features window for the stereotype:

a. On the General tab:

– Click the New Term check box to make this a New Term stereotype for this
profile.
– From the Applicable to drop-down list, select the Project check box to make
this New Term stereotype applicable to a project.
b. On the Properties tab, set the elements you want to appear for the Add New menu
through the use of the following properties:

– General::Model::CommonList property if you want to re-organize the

common list section of the Add New menu.
– General::Model::SubmenuList, General::Model::Submenu#List, and
General::Model::Submenu#Name if you want to re-organize the bottom
section of the Add New menu
– General::Model::AddNewMenuStructure property if you want to
completely customize the Add New menu.
Note that using this property overrides the other properties mentioned in this
topic.
c. Click OK.

Rational Rhapsody 505

Customizations for Rational Rhapsody

5. Set the stereotype for the project (in this example, Project2) to the New Term stereotype
(in this example, MyProfile).

a. Open the Features window for the project.

b. On the General tab, in the Stereotype drop-down list, select the check box for
stereotype (in this example, MyProfile).

c. Click OK.

6. To confirm your changes, right-click a package in your project and select Add New. Only
those elements you entered in the CommonList property and/or SubmenuList,
Submenu#List, and Submenu#Name properties, or AddNewMenuStructure appear, as long
as they are applicable to your project.

7. Make a corresponding text file for your custom profile and give it the same name but with
the .txt extension. Add a description for the profile. The content of the text files displays
on the description area of the New Project window.
For example, if your customized profile is MyProfile.sbs, create a MyProfile.txt file.

8. Copy the .sbs file for the profile and the corresponding .txt file to <Rational Rhapsody
installation path>\Share\Profiles\<customized profiles foldername>. For
example, you would place a copy of the MyProfile.sbs and MyProfile.txt files in, for
example, C:\Rhapsody\Share\Profiles\CustomProfiles.

If you have packages under your profile, choose to not make each package its own
separate unit so that you can keep the entire profile in a single .sbs file. Right-click the
package, select Unit > Edit Unit, and clear the Store in separate file check box on the
Unit Information window that opens).

9. To use the custom profile, when you create a new project, select the profile from the
Project Type drop-down list of the New Project window.

506 User Guide

 Creating a Rational Rhapsody plug-in

Creating a Rational Rhapsody plug-in

Rational Rhapsody plug-ins are Java applications that users can write to extend the capabilities in
Rational Rhapsody. Rational Rhapsody loads these applications into its process, and provides the
applications with an interface to the functions in Rational Rhapsody.

The capabilities added via plug-ins can be accessed through customized menu items integrated
into the out-of-the-box menus in Rational Rhapsody. Plug-ins can also provide capabilities that are
not opened directly by the user via the GUI, but rather are triggered by specific Rational Rhapsody
events, such as model checking or code generation. Plug-ins can respond to any of the events
defined in the Rational Rhapsody Callback API.

To write and prepare a plug-in for use with Rational Rhapsody:

1. Write the Java application.

2. Create a .hep file that contains the information that Rational Rhapsody requires to load the
plug-in, or add this information to an existing .hep file if you have already created one.

3. Attach the .hep file to a profile.

Writing a Java plug-in for Rational Rhapsody

While the steps described in this section can be carried out using any Java IDE, the text and screen
captures provided demonstrate how to perform these steps in Eclipse (version 3.4).

In terms of writing the Java code for your plug-in, you should:

1. Create a new Java project

2. Add the Rational Rhapsody library to the project's build path

3. Define a Java class for the plug-in

4. Implement the required methods

Creating a new Java project

To create a new Java project:

From the Eclipse main menu, select File > New > Project > Java Project.

Rational Rhapsody 507

Customizations for Rational Rhapsody

Adding Rational Rhapsody library to project build path

To add the Rational Rhapsody library to the project's build path:

1. In the Package Explorer View, right-click the project you created, and then select Build
Path > Configure Build Path.

2. Go to the Libraries tab and click Add External JARs.

3. Select rhapsody.jar, under <Rational Rhapsody installation path>\Share\JavaAPI

4. After rhapsody.jar has been added to the list, expand it and set the Native library location
to <Rational Rhapsody installation path>\Share\JavaAPI

508 User Guide

 Creating a Rational Rhapsody plug-in

Defining Java class for plug-in

To define a Java class for the plug-in:

1. In the Package Explorer View, right-click the project, and then select New > Class

2. When the New Java Class window is displayed, give the class a name, enter
RPUserPlugin for the Superclass, and make sure the Inherited abstract methods check
box is selected.

Implementing the required methods

Your plug-in class must implement the following methods:
//called when the plug-in is loaded
public abstract void RhpPluginInit(final IRPApplication rhpApp);

//called when the plug-in's menu item under the "Tools" menu is selected
public void RhpPluginInvokeItem();

//called when the plug-in popup menu (if applicable) is selected

public void OnMenuItemSelect(String menuItem);

Rational Rhapsody 509

Customizations for Rational Rhapsody

//called when the plug-in popup trigger (if applicable) is fired

public void OnTrigger(String trigger);

//called when the project is closed - if true is returned, the plug-in will be
unloaded
public boolean RhpPluginCleanup();

//called when Rhapsody exits

public void RhpPluginFinalCleanup();

Creating a .hep file for the plug-in

To provide Rational Rhapsody with the information necessary to load your plug-in, you must
create a .hep file or add this information to an existing .hep file if you have already created one.

.hep file structure

To understand the types of information that must be included for plug-ins in .hep files, it's best to
start with the issue of what types of elements can be described in .hep files.

.hep files are used to describe the following items:

helpers
plug-ins
plug-in commands
While these items differ from one another, they use the same .hep file entries to provide Rational
Rhapsody with the required information.

Helpers are also used to extend the capabilities in Rational Rhapsody, but they use a different
mechanism than plug-ins. Helpers are basically stand-alone applications. Plug-ins, on the other
hand, are not stand-alone applications. They just use the Rational Rhapsody callback mechanism
to respond to Rational Rhapsody events.

Plug-in commands don't really add any functionality of their own; they just describe context menu
items that Rational Rhapsody should add to allow you to open a certain plug-in.

For plug-ins, the .hep file must contain the following information:

the number of items (plug-ins/helpers/plug-in commands) defined in the file

the name of the plug-in
the Java class that implements the required methods
the Java classpath used by your plug-in

510 User Guide

 Creating a Rational Rhapsody plug-in

an indication that the item is a plug-in (not a helper or plug-in command)

an indication of whether or not a menu item should be added to the Tools menu
The best way to describe the required syntax for the .hep file is to look at an example.
[Helpers]
Category for the entries that follow

Note
The .hep file must contain a [Helpers] section because the helper recognition mechanism
is the same one used when you include helper definitions in your rhapsody.ini file, which
has other sections as well. Since plug-ins are usually designed for use by groups of users, in
most cases it does not make sense to include the plug-in definition information in the
rhapsody.ini file, which is unique to each user.
numberOfElements=2
Number of plug-ins/helpers described in the file
name1=Diagram Formatter
The name that will appear on the Tools menu (if isVisible is set to 1)
JavaMainClass1=JavaPlugin.PluginMainClass
The Java class containing the plug-in code
JavaClassPath1=$OMROOT\..\Samples\JavaAPI Samples\Plug-in
Path for locating the java classes required by the plug-in. Keep in mind that if .jar files are
used, the classpath should include the names of the .jar files.
isPlugin1=1
Indicates the item is a plug-in (as opposed to a helper, which is the default, or a "plug-in
command")
isVisible1=1
Indicates that the name should be displayed in the Tools menu.

The entries below describe a "plug-in command"

name2=Format Diagram
The text that will appear in the context menu
isPluginCommand2=1
Indicates that this is a plug-in command (as opposed to a helper or plug-in)
command2=Diagram Formatter

Rational Rhapsody 511

Customizations for Rational Rhapsody

Then name of the plug-in that will be opened by this context menu item
applicableTo2=ObjectModelDiagram
Indicates the context to which the menu will be added. In this case, when you right-click an
OMD in the browser, you will see the option "Format Diagram".
isVisible2=1
Indicates that the menu item should be displayed

If you would like to see another sample .hep file, take a look at the .hep file for the plug-in sample
included with <Rational Rhapsody installation path>\Samples\ExtensibilitySamples\
Simple Plug-in\SimplePluginProfile.hep).

Attaching a .hep file to a profile

To attach your .hep file to a profile, do one of the following actions:

Give the .hep file the same name as the profile, and place it in the same directory as the
profile's .sbs file
Indicate the path to the .hep file in the value of the property
General::Profile::AdditionalHelpersFiles for the profile

Troubleshooting Rational Rhapsody plug-ins

If the plug-in does not appear to be loaded, or if it does not respond as expected to Rational
Rhapsody events, you can log Rational Rhapsody's attempts to interact with the plug-in. To have
Rational Rhapsody create such a file, add the following entry to the [General] section of the
rhapsody.ini file:
JavaAPILogFile=[path and filename to use]
The log file does not clear its contents between Rational Rhapsody sessions. You might want to
remove the JavaAPILogFile entry from the rhapsody.ini file as soon as you have solved the
problem.

In the log file, you might encounter the following common errors:

ClassNotFoundException: <Class name> - check that the classpath is correct

UnsupportedClassVersionError: <Class name> - indicates that the class was compiled
with a newer version of Java than the one that Rational Rhapsody is using. Try to compile
your plug-in with lower compliance, or change the JVM used by Rational Rhapsody
(specified in the JVM section in the rhapsody.ini file).
NoSuchMethodException: <Class name>.<Method signature> - make sure the method has
been defined in your plug-in class

512 User Guide

 Creating a Rational Rhapsody plug-in

Debugging Rational Rhapsody plug-ins

You can debug your plug-in:

as a stand-alone Java application

from within a Rational Rhapsody process

Debugging as a stand-alone Java application

To debug as a stand-alone application, you will need to write a main operation that simulates a
Rational Rhapsody callback. Below is an example:
public static void main(String[] args) {
//create an instance of my plug-in
MyPlugin myPlugin = new MyPlugin ();
//get Rhapsody application that is currently running
IRPApplication app
=RhapsodyAppServer.getActiveRhapsodyApplication();
//init the plug-in
myPlugin.RhpPluginInit(app);
//simulate a call to the plug-in
myPlugin.RhpPluginInvokeItem();
}

Once you have included such a main operation, you can run Rational Rhapsody and debug the
plug-in as you would any other Java application.

Debugging from within Rational Rhapsody

To debug from within Rational Rhapsody:

1. Add the following debug options to the JVM section of the rhapsody.ini file:
[JVM]
Options=ClassPath,LibPath,Debug1,Debug2,Debug3
Debug1=-Xnoagent
Debug2=-Xdebug
Debug3=-Xrunjdwp:transport=dt_socket,address=6743,server=y,suspend=y

Rational Rhapsody 513

Customizations for Rational Rhapsody

2. Open your Java plug-in project in Eclipse and create a Remote Java Application
configuration as follows:

a. Choose Run > Debug Configurations.

b. In the Debug Configurations window, right-click Remote Java Application, and

then select New.

c. Set the port number to 6743 or any other number that you entered for "address" in the
JVM settings in the rhapsody.ini file.

3. Open Rational Rhapsody and open the project that loads your plug-in. Once the project is
loaded, Rational Rhapsody will wait until you start the debug session.

4. Set breakpoints in your code and start the debug session.

514 User Guide

 Creating a Rational Rhapsody plug-in

The simple plug-in sample

The Rational Rhapsody installation contains a sample plug-in called Simple Plug-in (under
ExtensibilitySamples).

To see the capabilities that this sample plug-in adds to Rational Rhapsody, add
SimplePluginProfile.sbs to a Rational Rhapsody model "As Reference".

This profile will load the plug-in and a message will be displayed indicating the Rational
Rhapsody build number you are using.

The plug-in adds the following menu items:

SimplePlugin under the Tools menu - when you select this menu item, Rational Rhapsody
displays properties that were overridden in the project.
Invoke SimplePlugin For OMD, Invoke SimplePlugin For Class, and Invoke
SimplePlugin For Package, for the context menus for OMDs, classes, and packages,
respectively. Selecting these context menu items will display the element's name.
In addition, the plug-in causes messages to be displayed at the following points: before code
generation, before project save, after project save, before check model.

Rational Rhapsody 515

Customizations for Rational Rhapsody

516 User Guide

 Use case diagrams

Use case diagrams (UCDs) model relationships between one or more users (actors) and a system
or class (classifier). You use them to specify requirements for system behavior. In addition,
Rational Rhapsody UCDs depict generalization relationships between use cases as defined in the
UML (see Creating generalizations). Rational Rhapsody does not generate code for UCDs.

Use case diagrams overview

Use cases (for example, wash dishes and service dishwasher) represent the user’s expectation for a
system. Actors (a cleansing engineer and service person) represent any external object that
interacts with the system. Uses cases reside inside the system boundary, and actors reside outside.
Association lines show relationships between the use cases and the actors. The following UCD
demonstrates these features.

System Boundary

Generalization

Use Case Actor

Association

Rational Rhapsody 517

Use case diagrams

Opening an existing use case diagram

To open an existing use case diagram in the drawing area:

1. Double-click the diagram name in the browser.

2. Click OK. The diagram opens in the drawing area.

As with other Rational Rhapsody elements, use the Features window for the diagram to edit its
features, including the name, stereotype, and description. For more information, see The Features
window.

518 User Guide

 Create use case diagram elements

Create use case diagram elements

The following sections describe how to use the use case diagram drawing tools to draw the parts of
a use case diagram. For basic information on diagrams, including how to create, open, and delete
them, see Graphic editors.

Use case diagram drawing tools

The Diagram Tools for a use case diagram contains the following tools:

Drawing
Button Name Description
Tool
Use Case Draws a representation of a user-visible function. A use case can be large or small,
but it must capture an important goal of a user for the system.

Actor Represents users of the system or external elements that either provide information
to the system or use information provided by the system.
Package Groups systems or parts of a system into logical components.

Association Shows relationships between actors and use cases.

Generalization Shows how one use case is derived from another. The arrow head points to the
parent use case.

Dependency Defines dependencies between an actor and a use case, between two actors, or
between two use cases.
Boundary box Delineates the design scope for the system and its external actors with the use
cases inside the system boundary and the actors outside.
Flow Provides a mechanism for specifying exchange of information between system
elements at a high level of abstraction. This functionality enables you to describe the
flow of data and commands within a system at a very early stage, before committing
to a specific design. As the system specification evolves, you can refine the
abstraction to relate to the concrete implementation.

For detailed information on flows, see Flows and flowitems.

Rational Rhapsody 519

Use case diagrams

System boundary box

The system boundary box should be the first element placed in a UCD. It distinguishes the border
between use cases and actors (use cases are inside the borders of the system boundary box and
actors are outside of it).

To create a system boundary box:

1. Click the Boundary box button .

2. Click once in the drawing area. Rational Rhapsody creates a boundary box named System
Boundary Box. Alternatively, click-and-drag with the mouse to draw the system boundary
box.

3. If wanted, edit the default name and press Enter.

Use cases
Use cases represent the externally visible behaviors, or functional aspects, of the system. They
consist of the abstract, uninterpreted interactions of the system with external entities. This means
that the content of use cases is not used for code generation. A use case is displayed in a UCD as
an oval containing a name.

Creating a use case

To create a use case:

1. Click the Use Case button .

2. Click once in the diagram or click-and-drag with the mouse to draw a use case of a
specific size. By default, the use case is named usecasen, where n is an integer greater
than or equal to 0.
3. If wanted, edit the default name and press Enter.

The new use case is displayed in both the UCD and the browser. The browser icon for a use case is
an oval.

520 User Guide

 Create use case diagram elements

Modify the features of a use case

Use the Features window to define these use case features.

Name allows you to replace the default name with the name you want for this use case.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the use case, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.

Note that the COM stereotypes are constructive; that is, they affect code generation.
Default Package specifies a group for this use case.

Adding attributes to a use case

Because a use case is a stereotyped class, it can have attributes. No code is generated for these
attributes. Rational Rhapsody does not display attributes in the UCD. To access attributes for a use
case, use the browser.

To add a new attribute to a use case:

1. Select the use case in the UCD editor.

2. Right-click the use case, and then select New Attribute. The Attribute window opens.

3. Type a name for the attribute in the Name field.

Use the L button next to the name field to assign a logical label. For more information on
labels, see Descriptive labels for elements.
4. Select the Type, Visibility, and Multiplicity for the attribute.

5. Type a description in the Description tab.

6. Click OK.

To add an existing attribute to a use case:

1. In the browser, locate the class that contains the attribute.

2. Click-and-drag the attribute to the use case in the browser. This creates a separate copy of
the attribute under the use case.

Note
If you click-and-drag an attribute from one use case to another, the attribute is moved, not
copied.

Rational Rhapsody 521

Use case diagrams

Adding operations to a use case

Because a use case is a stereotyped class, it can have operations.

To add a new operation to a use case:

1. Select the use case in the UCD editor.

2. Right-click the use case, and then select New Operation. The Primitive Operation
window opens.

3. Type a name for the operation in the Name field.

4. If wanted, specify a stereotype.

5. Select the visibility of the operation.

6. Select a type for the operation in the Type field.

7. Select the Return Type for the operation.

8. Specify the operation modifiers.

9. Add any arguments using the Arguments section.

10. Type a description in the Description tab.

11. Select the Implementation tab.

12. Type the implementation code for the operation in the Implementation text box.

Note: Code is not generated for the contents of use cases. This implementation is for
descriptive purposes only.
13. Click OK.

522 User Guide

 Create use case diagram elements

Adding extension points

To create an extension point for the base use case:

1. Right-click the use case in a diagram.

2. Select Features and click New on the General tab.

3. Type a name for the new extension point and click OK.

Creating a statechart or activity diagram for a use case diagram

Because use cases are stereotyped classes, it is possible to add a statechart or an activity diagram.

To add a statechart or activity diagram to a use case:

1. Select the use case in the UCD editor.

2. Right-click the use case, and then select either New Statechart or New Activity
Diagram.

For more information on these diagrams, see Statecharts and Activity diagrams.

Rational Rhapsody 523

Use case diagrams

Actors
Actors are the external entities that interact with a use case. Typical actors that operate on real-
time, embedded systems are buses (for example, Ethernet or MIB), sensors, motors, and switches.
An actor is represented as a figure in UCDs.

Actors are a kind of UML classifier similar to classes and they can participate in sequences as
instances. However, actors have the following constraints imposed on them:

They cannot aggregate or compose any elements.

They generalize only from other actors.
They cannot be converted to classes, or vice versa.
Rational Rhapsody can generate code for an actor, which can be used in simulation testing of the
system you are building. For more information, see Generating Code for Actors.

Creating an actor
To create an actor:

1. Click the Actor button , and then click once in the UCD. Alternatively, click-and-drag
to draw the actor.

2. Edit the default name, and then press Enter.

Modify the features of an actor

The Features window enables you to define the features of an actor. An actor has the following
features:

Name specifies the name of the element. The default name is actor_n, where n is an
incremental integer starting with 0.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the actor, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating labels, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Main Diagram specifies the main diagram for the actor.

More than one UCD can contain the same use case or actor. You can select one of these
diagrams to be the main diagram for the use case or actor. This is the diagram that will
open when you select the Open Main Diagram option in the browser.
Concurrency specifies the concurrency of the actor. The possible values are as follows:

524 User Guide

 Create use case diagram elements

– Sequential where the element will run with other classes on a single system
thread. This means you can access this element only from one active class.
– Active where the element will start its own thread and run concurrently with
other active classes.
Defined In specifies which element owns this actor. An actor can be owned by a package,
class, or another actor.
Class Type specifies the class type. The possible values are as follows:
– Regular creates a regular class.
– Template creates a template. To specify the necessary arguments, click the
Arguments button.
– Instantiation creates an instantiation of a template.

To create an instance of a class, select the Instantiation radio button and

select the template that the instance is from. For example, if you have a
template class A and create B as an instance of that class, this means that B is
created as an instance of class A at run time.

To specify the necessary arguments, click the Arguments button.

Adding attributes and operations

Attributes and operations are added to actors just as they are added to classes.

To add an attribute or operation to an actor:

1. Open the Features window for the actor.

2. Select the Attributes tab or Operations tab, as appropriate.

3. Select the <New> label. A new row is displayed, with the default values filled in.
4. If needed, change the default values for the new attribute or operation.

5. Click OK.

For detailed information on creating attributes and operations, see Defining the attributes of a class.

Rational Rhapsody 525

Use case diagrams

Creating a statechart, activity, or structure diagram

Because an actor is a special type of class, it can have a statechart, an activity diagram, or a
structure diagram.

To use the editor to add one of these diagrams to an actor:

1. Select the actor in the UCD editor.

2. Right-click the actor, and then select New Statechart, New Activity Diagram, or New
Structure Diagram.

For more information on these diagrams, see Statecharts, Activity diagrams, or Structure diagrams.

Generating code for an actor

To generate code for an actor:

1. Locate the active configuration in the browser.

2. Open the Features window for the active configuration.

3. On the Initialization tab, select Generate Code for Actors.

Alternatively, you can generate code for the actor by right-clicking on the actor in the UCD and
selecting Generate.

When you generate code for the configuration, code is also generated for any actors that are part of
the configuration. For detailed information on configurations, see Component configurations in the
browser.

Creating packages
Packages logically group system components. They are represented in UCDs as a file folder.

To create a package:

1. Click the Package button , and then click once in the UCD. Alternatively,
click-and-drag with the mouse to draw the package.

2. Edit the default name, and then press Enter.

The new package will be displayed in both the diagram and the browser (listed under Packages).

526 User Guide

 Create use case diagram elements

Creating associations
Associations represent lines of communication between actors and use cases. Use cases can
associate only with actors, and vice versa.

To create an associations:

1. Click the Association button .

2. Click either the actor or the use case. Note that the crosshairs change to a circle with
crosshairs when you are on an element that can be part of an association.
3. Move the cursor to the target of the association and click once. If the source is an actor, the
target must be a use case, and vice versa.

4. Type a name for the association, then press Enter.

The new association is displayed in both the UCD and the browser (under the actor’s
Association Ends category).

For information on modifying an association, see Association features. Association features

include the type, name, roles, multiplicity, qualifiers, and description.

Creating generalizations
UML allows for generalization as a way of factoring out commonality between use cases. In other
words, it provides a means to derive one use case from another. Generalizations are allowed
between use cases and actors.

To create a generalization relationship:

1. Click the Generalization button.

2. Click the derived use case.

3. Move the cursor to the closest edge of the super-use case and click once.

Rational Rhapsody 527

Use case diagrams

Creating dependencies
A dependency is a directed relationship from a client to a supplier in which the functioning of a
client requires the presence of the supplier, but the functioning of the supplier does not require the
presence of the client. Generalizations are allowed between any two UCD elements: use case,
actor, or package.

To create a dependency relationship:

1. Click the Dependency button .

2. Select the client element.

3. Move the cursor to the closest edge of the supplier element and click once.

You can set the dependency stereotype using the Features window. See Dependencies.

Sequences
UCDs assist in the analysis phase of a project. They capture hard and firm constraints at a high
level. As design decisions are made, you further decompose UCDs to create more possible use
cases and scenarios, or sequences, that implement the use case. Each use case has a folder in the
browser containing some of its possible sequences.

Scenarios describe not only the main path through a use case, but can also include background
environmental and situational descriptions to set the stage for future events. In other words, they
can provide detailed definitions of preconditions for a use case. Therefore, a sequence describes
the main path through a use case, whereas a variant, represented by a child use case, describes
alternate paths. For example, consider a VCR. One sequence of the InstallationAndSetup use case
might be the following steps:

1. Add the VCR and accessories.

2. Insert batteries in the remote control.

3. Connect the antenna or cable system to the VCR.

4. Set the CH3/CH4 switch.

5. Turn on the VCR and select an active channel.

6. Learn to use the TV/VCR button.

7. Test the VCR connections.

The specific sequence of steps through a particular use case is better expressed through a sequence
diagram. For detailed information, see Sequence diagrams.

528 User Guide

 Object model diagrams

Object model diagrams (OMDs) specify the structure and static relationships of the classes in the
system. Rational Rhapsody OMDs are both class diagrams and object diagrams, as specified in the
UML. They show the classes, objects, interfaces, and attributes in the system and the static
relationships that exist between them.

Structure diagrams focus on the objects used in the model. Although you can put classes in
structure diagrams and objects in the OMD, the toolbars for the diagrams are different to allow a
distinction between the specification of the system and its structure. For more information, see
Structure diagrams.

Object model diagrams overview

More than simply being a graphical representation of the system structure, OMDs are constructive.
The Rational Rhapsody code generator directly translates the elements and relationships modeled
in OMDs into source code in a number of high-level languages. The following sample OMD
shows a dishwasher project.

Rational Rhapsody 529

Object model diagrams

In this diagram, the thick sidebars on the Dishwasher class denote that it is the active class.

You can specify and edit operations and attributes directly within class and object boxes. Simply
highlight the appropriate element to make it active, then type in your changes. To open the
Features window for a given attribute or operation, just double-click the element within the
compartment.

Note
To add a new operation or attribute, press the Insert key when the appropriate compartment
is active.

Object model diagram elements

The following sections describe how to use the object model diagram drawing tools to draw the
parts of an object model diagram. For basic information on diagrams, including how to create,
open, and delete them, see Graphic editors.

Object model diagram drawing tools

The Diagram Tools for an object model diagram includes the following tools:

Drawing
Button Name Description
Tool
Select A pointing tool to identify parts of the diagram requiring changes or additions.

Object A structural building block of a system. Objects form a cohesive unit of state (data)
and services (behavior). Every object has a public part and an private part. For more
information, see Objects.
Class Defines properties that are common to all objects of that type. For more information,
see Creating classes.

Composite A container class. You can create objects and relations inside a composite class. For
class more information, see Creating composite classes.

Package A group of classes. For more information, see Creating a package.

File Available only in Rational Rhapsody in C has an additional icon. Use it to create file
model elements. A file is a graphical representation of a header (.h) or code (.c)
source file. For more information, see Files.
Port Draws connection points among objects and their environments.

Inheritance Shows the relationship between a derived class and its parent.

530 User Guide

 Object model diagram elements

Drawing
Button Name Description
Tool
Association Creates connections that are necessary for interaction such as messages.

Directed Indicates the only object that can send messages to another object. For more
association information, see Directed associations.

Aggregation Specifies an association between an aggregate (whole) and a component part. For
more information, see Aggregation associations.

Composition Defines a class that contains another part class. For more information, see
Composition associations.

Link Creates an association between the base classes of two different objects. For more
information, see Links.

Dependency Creates a relationship in which the proper functioning of one element requires
information provided by another element. For more information, see Dependencies.

Flow Specifies the flow of data and commands within a system. For more information, see
Flows and flowitems.

Realization Specifies a realization relationship between an interface and a class that implements
that interface. For more information, see Realization.

Interface Adds a set of operations that publicly define a behavior or way of handling
something so knowledge of the internals is not needed.

Actor Represents an element that is external to the system. For more information, see
Actors.

The following sections describe how to use these tools to draw the parts of an OMD. For basic
information on diagrams including how to create, open, and delete them, see Graphic editors.

Objects
Rational Rhapsody separates objects from classes in diagrams. There are two types of objects:

Objects with explicit object types specifies only the features that are relevant for the
instance. An explicit object instantiates a “normal” class from the model.

Objects with implicit types enables you to specify other features that belong to
classes, such as attributes, operations, and so on. An implicit object is a combination of
an instance and a class. Technically, the class is hidden.
Note that Rational Rhapsody in J does not support objects with implicit types.

An object is basically an instance of a class; however, you can create an object directly without
defining a class. Objects belong to packages and parts belong to structured classes; the browser
separates parts and objects into separate categories.

Rational Rhapsody 531

Object model diagrams

Opening an existing object model diagram

To open an existing object model diagram in the drawing area:

1. Double-click the diagram name in the browser.

2. Click OK. The diagram opens in the drawing area.

As with other Rational Rhapsody elements, use the Features window for the diagram to edit its
features, including the name, stereotype, and description. For more information, see The Features
window.

Creating an object
To create an object:

1. Click the Object icon in the Diagram Tools.

2. Click, or click-and-drag, in the drawing area.

3. Edit the default name, then press Enter.

If you specify the name in the format <ObjectName:ClassName> (for an object with
explicit type) and the class <ClassName> exists in the model, the new object will
reference it. If it does not exist, Rational Rhapsody prompts you to create it.

Object characteristics
By default, Rational Rhapsody creates objects with implicit type. In the OMD, an object is shown
like a class box, with the following differences:

The name of the object is underlined.

The multiplicity is displayed in the upper, left-hand corner.

The following example shows an object of explicit type:

532 User Guide

 Object characteristics

Parts in an object model diagram

As with classes, you can display the attributes and operations in the object. For more information,
see Display option settings.

The following example shows an object model diagram that contains parts.

Rational Rhapsody 533

Object model diagrams

Object features
The Features window enables you to change the features of an object, including its concurrency
and multiplicity.

An object has the following features:

Name specifies the name of the element. The default name is object_n, where n is an
incremental integer starting with 0.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the object, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Main Diagram specifies the name of the diagram of which this is a part.
Concurrency specifies the concurrency of the object. This field is available only for
objects with implicit type. The possible values are as follows:
– Sequential means the element will run with other classes on a single system
thread. This means you can access this element only from one active class.
– Active means the element will start its own thread and run concurrently with
other active classes.
Type specifies the class of which the object is an instance. To view the classes for that
class, click the Invoke Feature Dialog button next to the Type field.

In addition to the names of all the instantiated classes in the model, this list includes the
following choices:
– <Implicit> specifies an implicit object
– <Explicit> specifies an explicit object
– <New> enables you to specify a new class
– <Select> enables you to browse for a class using the selection tree
Multiplicity specifies the number of occurrences of this instance in the project. Common
values are one (1), zero or one (0,1), or one or more (1..*).
Initialization specifies the constructor being called when the object is created. If you click
the Ellipsis button, the Actual Call window opens so you can see the details of the call.
If the part does not have a constructor, with parameters, this field is dimmed.

Relation to whole enables you to name the relation for a part. If the object is part of a
composite class, enable the Knows its whole as check box and type a name for the
relation in the text box. This relation is displayed in the browser under the Association

534 User Guide

 Object characteristics

Ends category under the instantiated class or implicit object.

If the Relation to whole field is specified on the General tab, the Features window
includes tabs to define that relation and its properties. However, on the tab that specifies
the features of its whole (in the illustration of the itsController tab), only the fields Name,
Label, Stereotype, and Description can be modified.

Converting object types

You can easily change the type of an object using the Features window for the object.

If you convert an object with implicit type to an object with explicit type (by selecting <Explicit>
in the Type field), a new class is created. By default, the name of the new class is <object
name>_class.

If you convert an object of explicit type to an object of implicit type, the following actions occur:

The original class is copied into the object of implicit type.

Graphical relations are removed.
Symmetric associations become directional.
Links disconnect from associations.

Converting classes to objects

To convert a class to an object, right-click the class in the diagram and select Make an Object.
Rational Rhapsody converts the class to an object named its<ClassName>:<ClassName>. For
example, if you converted class A to an object, the name of the object would be itsA:A.

Rational Rhapsody 535

Object model diagrams

Code generation for objects

For objects with explicit type, code is generated as in previous versions of Rational Rhapsody. The
following table lists the results of generating code for objects with implicit type.

Situation Results of Code Generation

Implicit type During code generation, the object is mapped in
two parts:
• An implicit class with the name <object>_C.
• The instance of the class in its owner (either a
composite class or package). The name of the
instance is <object>.
Implicit type in a package The code for the instance is generated in the
(global) package file and the code for the implicit class is
generated into files named <object>.h and
<object>.cpp.
Implicit type in a structured The code for the instance is generated in the
class (part) composite class file and the code for the implicit
class is generated as a nested class of the
composite (in the file for the composite).
Embeddable objects The default code scheme for code generation for
objects is changed to embeddable. The default
values of the following properties were changed:
• CPP_CG::Class::Embeddable is Checked
• CPP_CG::Relation::ImplementWithSta
ticArray is FixedAndBounded

536 User Guide

 Object characteristics

Editing the declaration order of objects

To change the order of objects:

1. In the browser, right-click the Objects category icon and then select Edit Objects Order.
The Edit Objects declaration order window opens and lists all the files and objects in the
current package.

2. Unselect the Use default order check box.

3. Select the object you want to move.

4. Click Up to generate the object earlier or Down to generate it later.

5. Click OK.

Changing the value of an instance

You can specify the value of attributes for instances. An attribute value is the value assigned to an
attribute during run time. This functionality enables you to describe a possible setup of objects and
parts at a certain point in their lifecycle, you can see a “snapshot” of the system, including the
instances that exist and their values. To support this functionality, the Features window for
instances includes a new column, Value.

Note
Initial values are features of the attributes of the class, whereas instance values characterize
the specific instance of the class (that object).

Rational Rhapsody 537

Object model diagrams

For example, consider the class, Date, and an object of Date called newYear2004. The class Date
has the attributes Day, Month, and Year. The following example shows the initial values for the
class Date.

The following example shows the attributes for object newYear2004 of class Date. Note that the
Show Inherited check box specifies whether to display the inherited attributes so you can easily
modify them.

538 User Guide

 Object characteristics

Click the Specification View icon to view the attributes and operations of an object in the OMD.
The following OMD shows the class, Date, and the object of Date called newYear2004.

In the OMD, the object values are displayed using the following format:
[visibility]<attribute name>:<attribute type>=<value>
Note the following information:

Instance values are always displayed. To hide the entire attribute, right-click the object and
select Display Options.
Both the instance and the class must be “available” in the model.

Rational Rhapsody 539

Object model diagrams

Creating a vacuum pump model as an example

The following model shows how to use instance attribute values to take snapshots of a vacuum
pump model at different stages in the lifecycle.

The vacuum pump removes the air from a chamber. The model needs to show the state of the
system at various points in time, the initial value, the value after one hour, and the final value.

The following example shows the OMD for the model.

To create a vacuum pump model as an example:

1. Create a package called ConstantPumping.

2. Set the CG::Class::UseAsExternal property to Checked so the package is considered

external (and code will not be generated for it).

Alternatively, you can create a new stereotype for the class («snapshot»), then set this
property to Checked.

3. In this package, each phase is represented by a different class. For the initial conditions,
create a class called InitialConditions.

540 User Guide

 Creating a vacuum pump model as an example

4. Add a structure diagram to InitialConditions and add the elements (and their attribute
values) to the diagram.

Rational Rhapsody 541

Object model diagrams

5. To show the conditions after an hour, copy the InitialConditions class and rename it
AfterAnHour. Specify the attribute values for this stage in the process. The following
example shows the attribute values after the pump has been running for an hour.

542 User Guide

 Creating a vacuum pump model as an example

6. To show the final values for the system, copy the InitialConditions class and rename it
FinalState. Specify the attribute values for this stage in the process. The following
example shows the final values.

Rational Rhapsody 543

Object model diagrams

7. To show the order and transitions between snapshots, you can draw a simple OMD, as
shown in the following example.

544 User Guide

 Creating classes

Creating classes
Classes can contain attributes, operations, event receptions, relations, components, superclasses,
types, actors, use cases, diagrams, and other classes. The browser icon for a class is a three-
compartment box with the top, or name, compartment filled in.

To create a class:

1. In the Diagram Tools, click the Class tool.

2. Click in the drawing area.

3. Edit the default class name.

4. Press Enter.

Class compartments
In the OMD, a class is shown as a rectangle with three sections, for the name, attributes, and
operations. You can select and move the line separating the attributes and operations to create
more space for either compartment.

Name

Attributes

Operations

If you shrink the box vertically, the operations and attributes sections disappear and the class
graphic shows only the class name. The attributes and operations reappear if you enlarge the
drawing.

When you rename a class in the OMD editor, the class name is changed throughout the model.

For more information about classes, see Classes and types.

Rational Rhapsody 545

Object model diagrams

Creating composite classes

Instances in a composite class are called parts. To identify a component in code (actions or
operations), use the expression instance-of-composite.name-of-part. The multiplicity of a
component is relative to each instance of the composite containing it. For example, each car has
one engine.

If the multiplicity is well-defined (such as 1 or 5), Rational Rhapsody creates the components at
run time, when the composite is instantiated. If an association is instantiated by a link, Rational
Rhapsody initializes the association at run time.

When a composite is destroyed, it destroys all its components.

To create a composite class:

1. Click the Composite Class tool.

2. Click in the diagram, or click-and-drag to create the composite class. The new composite
class is displayed in the diagram.

Because a composite class is a container class, you can create objects and relations inside it, as
shown in this example.

A composite class uses the same Features window as objects and parts (see Class features).

Another way of having the functionality of a composite class is to use a composition. For more
information, see Composition associations.

546 User Guide

 Creating a package

Creating a package
In Rational Rhapsody, every class belongs to a package. Classes drawn explicitly in a package are
placed in that package in the model. Classes not drawn explicitly in a package are placed in the
default package of the diagram. If you move a class to a package, it is also placed in that package
in the model. If you do not connect this diagram to a package with the browser, Rational Rhapsody
assigns the diagram to the default package of the model.

To draw a package in the diagram:

1. Select the Package icon.

2. Click once in the diagram. Now you must define the package using the Features window.
3. Right-click the package and select Features.

Package features
The Features window allows you to define the characteristics of a package, such as its Name or
Main Diagram.

Name specifies the name of the package. Package names cannot contain spaces or begin
with numbers.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the package, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.

Note that package stereotypes are not constructive (see Constructive dependencies).
Main Diagram specifies the name of the diagram of which this is a component.
The Description tab allows you to write a detailed description of the package. The Relations tab
lists all of the relationships of the package. The Tags tab lists the available tags for this package.
The Properties tab enables you to define code generation properties for the package.

Rational Rhapsody 547

Object model diagrams

Inheritance
Inheritance is the “mechanism by which more specific elements incorporate structure and behavior
of more general elements related by behavior.” Inheritance is also known as generalization, or a
“taxonomic relationship between a more general element and a more specific element. The more
specific element is fully consistent with the more general element and contains additional
information. An instance of the more specific element may be used where the more general
element is allowed.” (Both references are from the UML Specification, v1.3.)

Creating an inheritance with an inheritance arrow

You can create inheritance by drawing an inheritance arrow between two classes or by using the
browser. To create an inheritance arrow between two classes:

1. Click the Inheritance icon.

2. Click in the subclass.

3. Move the cursor to the superclass and click once to end the arrow.

An inheritance arrows points from the subclass to the superclass, with a large arrowhead on the
superclass end.

The browser icon for a superclass is an inheritance arrow:

The icon for the SuperClass category is a black arrow.

The icon for an individual SuperClass is a blue arrow.
Double-clicking a SuperClass icon in the browser opens the Features window for the superclass.

548 User Guide

 Creating a package

Creating inheritance in the browser

To create inheritance using the browser:

1. Right-click a class and then select Add New > SuperClass. The Add Superclass window
opens.

2. Use the list to specify the superclass.

3. Click OK.

Inheriting from an external class

To inherit from a class that is not part of the model, set the CG::Class::UseAsExternal property
for the superclass to Checked. This prevents code from being generated for the superclass.

To generate an #include of the superclass header file in the subclass, do one of the following
actions:

Add the external element to the scope of some component.

Map the external element to a file in the component.
Set the CG::Class::FileName property for the superclass to the name of its specification
file (for example, super.h). That file is included in the source files for classes that have
relations to it. If the FileName property is not set, no #include is generated.
Another way to inherit from an external class is to exclude the external class from the code
generation scope. For example, if you want a class to extend the Java class javax.swing.JTree
without actually importing it:

1. Draw a package javax.

2. Draw a nested package swing inside javax.

3. Draw a class JTree inside the swing package.

4. Exclude the javax package from the component (do not make it one of the selected
elements in the browser). This prevents the component from generating code for anything
in the javax package.
This gives the rest of the model the ability to reference the JTree class without generating code for
it. In this way, a class in the model (for example, MyJTree) can inherit from javax.swing.JTree.
If the subclass is public, the generated code is as follows:
import javax.swing.JTree;
...
public class MyJTree extends JTree {
...
}

Rational Rhapsody 549

Object model diagrams

If you need a class to import an entire package instead of a specific class, add a dependency (see
Dependencies) with a stereotype of «Usage» to the external package, in this case javax.swing.
The generated file will then include the following line:
import javax.swing.*
For more information on using external elements, see External elements.

Realization
Rational Rhapsody allows you to specify a realization relationship between an interface and a class
that implements that interface. This type of relationship is specified using the realization connector
in the Diagram Tools for object model diagrams.

Note
Realization is a "new term" based on the generalization element. This means that it is also
possible to right-click a generalization element in a diagram and then select Change To >
Realization.
The realization connector only serves a visual purpose when used in an object model diagram. The
code generation for realization relationships is not determined by the connector used between the
class and the interface, but by the application of the interface stereotype to the class element in the
diagram that represents the interface.

If you apply the interface stereotype to a class element, then the appropriate code will be generated
for the interface and the implementing classes in Rational Rhapsody in Java and Rational
Rhapsody in C.

For details regarding the code generation for realization relationships in C, see Components-based
Development in C.

550 User Guide

 Associations

Associations
In previous versions of Rational Rhapsody, the term “relations” referred to all the different kinds
of associations. Note that the term “relations” refers to all the relationships you can define between
elements in the model (not just classes), associations, dependencies, generalization, flows, and
links.

Associations are links that allow related objects to communicate. Rational Rhapsody supports the
following types of associations:

Bi-directional association where both objects can send messages back and forth. This is
also called a symmetric association. For more information, see Bi-directional associations.
Directed association where only one of the objects can send messages to the other. For
more information, see Directed associations.
Aggregation association defines a whole-part relationship. For more information, see
Aggregation associations.
Composition aggregation defines a relationship where one class fully contains the other.
For more information, see Composition associations.

Bi-directional associations
Bi-directional (or symmetric) associations are the simplest way that two classes can relate to each
other. A bi-directional association is shown as a line between two classes, and can contain control
points. The classes can be any mix of classes, simple classes, or composite classes.

When you create an association or an aggregation association between two classes and give it a
role name that already exists, you have created another view of an existing relation.

In previous versions of Rational Rhapsody, an association was described by one or two association
ends. An association can be composed of the following elements:

Association ends means the associated objects

Association element means a view of the association as a whole
Association class means an association element that has class characteristics (attributes
and operations)

Note
If you draw an anchor from a class to a relation (association, aggregation, or composition),
it semantically implies that the class is an association class for this relation. Removing the
icon changes the association class into a regular class.

Rational Rhapsody 551

Object model diagrams

Creating a bi-directional association

To create a bi-directional association between classes:

1. Click the Create Association icon .

2. Click in a class.

3. Click in another class.

In this example note the bi-directional Association line between two classes.

Note the following information:

Associations specify how classes relate to each other with role names. The relative
numbers of objects participating is shown with multiplicity.
You can move an association name freely.
If you remove the class at one end of an association from the view, the association is also
removed from the view. If you delete a class at one end of an association from the model,
the association is also deleted.
The role names and multiplicity are set in the Features window for the association. To edit
a role name or multiplicity, double-click it.
If you move an association line from between class x and class y to between class x and
class z, where z is a subclass of y, it is removed from y. But if z is a superclass of y, it
remains because all relationships with a superclass are shared by their subclasses. If z and
y are independent, Rational Rhapsody moves it from y to z.

552 User Guide

 Associations

Association features
The Features window enables you to change the features of an association, such as what it consists
of (for example, two ends or a single end) and its association ends. The following figure shows the
Features window for a bi-directional association.

A bi-directional association has the following features:

Name specifies the name of the association.

L specifies the label for the element, if any.Rational Rhapsody For information on creating
labels, see Descriptive labels for elements.
Stereotype specifies the stereotype of the association, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.

Rational Rhapsody 553

Object model diagrams

Consists of specifies whether the association consists of:

– A single association end (End <X>)
– Two given ends (Both Ends)
– An association element and two association ends (Association Element)
– An association class and two association ends (Association Class)
Note: There is no representation of the association class in the diagram, nor is there
code generation for the association class. The only representation of the
association class is in the Consists of field.
Association Ends specifies the ends of the association. If only one end is specified, the
Role Name field for End2 field is unavailable.

Using this group box, you can change the role name of each enabled end. An enabled end
is an end that is part of the specification of the association. The label under this field
contains the type of the association end (the class to which the end is connected), the
navigability of the end, and its aggregation kind. For a non-existing end, this label
contains only “Role of.”
Description describes the association. This field can include a hyperlink. For more
information, see Hyperlinks.

Note
If the association class or element does not exist, the Name, Stereotype, Label, and
Description fields are disabled.
In addition to the General tab, the Features window for an association contains the following tabs:

End1 or End2
End1 properties or End2 properties

554 User Guide

 Associations

If the Consists of field is set to Association Class, the window also includes tabs for attributes and
operations, as shown in this example.

Rational Rhapsody 555

Object model diagrams

The End1 and End2 tabs

The End1 and End2 tabs enable you to specify features of the individual ends of the association.
The following figure shows an End1 tab.

The End1 and End2 tabs contain the following fields:

Name specifies the name of the element.

L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the element, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Role of a read-only field that specifies the class, actor, or use case that plays a role in the
association.
Multiplicity specifies the number of occurrences of this instance in the project. Common
values are one (1), zero or one (0,1), or one or more (1..*).

556 User Guide

 Associations

Qualifier shows the attributes in the related class that could function as qualifiers.

A qualifier is an attribute that can be used to distinguish one object from another. For
example, a PIN number can serve as a qualifier on a BankCard class. If a class is
associated with many objects of another class, you can select a qualifier to differentiate
individual objects. The qualifier becomes an index into the multiple relation. Adding a
qualifier makes the relation a qualified association.
Aggregation Kind specifies the type of aggregation. The possible values are as follows:
– None means no aggregation.
– Shared (empty diamond)\ means shared aggregation (whole/part
relationship).
– Composition (filled diamond) means composition relationship. The instances
of the class at this end contains instances of the class at the other end as a part.
This part cannot be contained by other instances.
Navigable specifies whether the association allows access to the other class. Both ends of
a bi-directional association are navigable. In a directed association, the element that has
the arrow head is navigable; the other end is not. For more information, see Directed
associations.

The navigability of an association influences the appearance of the association arrow in

the diagram. If one end of a symmetric association is navigable and the other is not, the
association line includes an arrow head.
Description describes the association. This field can include a hyperlink. For more
information, see Hyperlinks.
Similarly, the End2 tab shows the features for the second end of the association.

Note that if an end is read only, its feature fields are also read-only.

The End1 and End2 properties tabs

The End1 properties and End2 properties tabs enable you to specify properties for the individual
ends of the association.

Rational Rhapsody 557

Object model diagrams

Directed associations
In a directed (or one-way) association, only one of the objects can send messages to the other. It is
shown with an arrow, as shown in this example.

Creating a directed association

To create a directed association:

1. Click the Directed Association icon .

2. Click in the source class.

3. Click in the destination class.

Rational Rhapsody draws an arrow between the two objects, with the arrow head pointing to the
target object.

558 User Guide

 Associations

Directed association features

The Features window enables you to change the features of a directed association, such as what it
consists of (for example, two ends or a single end) and its association ends.

The Features window for a directed association is the same as the Features window for a
bi-directional association (see Association features), but the available tabs are different. As shown
in the figure, a directed association has one role name and one multiplicity.

If the directed association is not named (as shown in the figure), the Consists of field is set to End
<X> and the window contains only the tabs General, End1, and End1 properties.

However, for a named directed association, the Consists of field of the Features window is set to
Association Element, which means there is one more non-navigable end. The window contains
the following additional tabs:

Association Tags specifies the tags that can be applied to this association. For more
information on tags, see Profiles.
Association properties specifies the properties that affect this association.

Aggregation associations
Associations and aggregation associations are similar in usage. An association portrays a general
relationship between two classes; an aggregation association shows a whole-part relationship.
When you create an association or an aggregation association between two classes and give it a
role name that already exists, you have created another view of the existing association.

An aggregation association is a whole-part relationship similar to the relationship between a

composite class and a part. Other than their graphic representations, these differ mainly in that the
composite/component relationship implies a whole lifetime dependency. Parts are created with
their composites and are destroyed with them.

An aggregation association is shown as a line with a diamond on one end. The side with the
diamond indicates the whole class, whereas the side with the line is the part class. In the following
sample Aggregation Association, the diamond is placed at the first point of the aggregation:

Rational Rhapsody 559

Object model diagrams

Creating an aggregation association

To create an aggregation:

1. Click the Aggregation icon .

2. Click in the class that represents the whole.

3. Click in the class the represents the part.

Aggregation association features

The Features window for an aggregation is the same as that for a bi-directional association. For
more information, see Association features.

Note that for an aggregation association:

Both ends are navigable.

The Aggregation Kind value for the diamond end of an aggregation association is set to
None; the other end must be set to Shared.

560 User Guide

 Associations

Composition associations
Another way of drawing a composite class is to use a composition association. A composition
association is a strong aggregation relation connecting a composite class to a part class
(component). The notation is a solid diamond at the composite end of the of the relationship, as
shown in this example.

The composite class has the sole responsibility of memory management for its part classes. As a
result, a part class can be included in only one composite class at a time. A composition can
contain both classes and associations.

Creating a composite association

To create a composite association:

1. Click the Composition icon .

2. Click the composite class.

3. Click the part class.

4. If wanted, name the composition.

5. Press Enter to dismiss the text box.

Composition association features

The Features window for compositions is the same as that for associations. For more information
about the available fields, see Association features.

Note that for a composition association:

Both ends are navigable.

The Aggregation Kind value for the filled-diamond end of the composition line is set to
None; the other end must be set to Composition.

Rational Rhapsody 561

Object model diagrams

Associations in the browser

An association can be represented in the browser as:

A single association end

Two association ends
An association element and two association ends
An association class and two association ends
Associations are listed in the browser under the category Association Ends under the owning
class, as shown in this example. Note that the browser display includes separate icons for each
association type.

562 User Guide

 Associations

Associations implementation
Rational Rhapsody implements associations using containers. Containers are objects that store
collections of other objects. To properly generate code for associations, you must specify the
container set and type within that set you are using for the association.

Generally, you use the same container set for all associations. You specify the container set using
the CG::Configuration::ContainerSet property. There are many options, depending on the
language you are using. You can assign various container types, as defined in the selected
container set, to specific relations. Container types include Fixed, StaticArray,
BoundedOrdered, BoundedUnordered, UnboundedOrdered, UnboundedUnordered, and
Qualified, among others. In addition, you can define your own container type called User. You
specify the container type using the Implementation and ImplementWithStaticArray properties
(under CG::Relation).

Associations menu
In addition to the common operations (see Edit elements), the menu for associations includes the
following options:

Select Association lists the available associations for this class, as shown in this example.
This functionality is useful when you have more than one association between the same
elements.

For more information, see Select associations.

Show Labels shows the role labels in the diagram.

Display Options enables you to specify how associations are displayed in the diagram. By
default, Rational Rhapsody displays the name of the association, and the multiplicity and
qualifiers for End1 and End2.

Rational Rhapsody 563

Object model diagrams

Select associations
In OMDs, you can select associations for classes that have more than one association defined
between the same two classes. To do this, hold down the right mouse button over an association
line to bring up the menu, then select Select Association.

Association names are displayed as follows:

If the association has a name, the name is listed.

If the association does not have a name and it is symmetric, the identifier uses the format
<role_1>-<role_2>.
If the association does not have a name and it is unidirectional, the identifier uses the
format -><role>.
If you select a different association from the list, the association line is directed to
reference the selected association.

564 User Guide

 Associations

Links
A link is an instance of an association. In previous releases of Rational Rhapsody, you could link
objects in the model only if there were an explicit relationship between their corresponding
classes. An association line between two objects meant the existence of two different model
elements:

An association between the objects’ classes

A link between the objects
Rational Rhapsody separates links from associations so you can have unambiguous model
elements for links with a distinct notation in the diagrams. This separation enables you to:

Specify links without having to specify the association being instantiated by the link.
Specify features of links that are not mapped to an association.
In addition, Rational Rhapsody supports links across packages, including code generation. To
support this functionality, the default value of the property
CG::Component::InitializationScheme was changed to ByComponent.

Creating a link
To create a link, there must be at least one association that connects one of the base classes of the
type of one of the objects to a base class of the type of the second object.

To create a link:

1. Click the Link tool.

2. Click the first object.

3. Click the second object.

4. If wanted, name the link and press Enter.

The new link is created in the diagram, and is displayed in the browser under the Link category.
Note that you can drag-and-drop links in the browser to other classes and packages as needed;
however, you cannot create links in the browser.

The following figure shows links in an OMD. Note that links shown in dark green to distinguish
them from associations, which are drawn in red. In addition, the names and multiplicity of links
are underlined.

Rational Rhapsody 565

Object model diagrams

By default, the role name and multiplicity of a link are not displayed. Right-click the link and
select Display Options to select the items you want to display. For more information, see Link
menu.

Note the following behavior:

Links can be drawn between two objects or ports that belong to objects. One exception is
the case when a link is drawn between a port that belongs to a composite class and its part
(or a port of its part).
When drawing a link, Rational Rhapsody finds the association that can be instantiated by
the newly drawn link and automatically maps the link to instantiate the association.
If you draw a link between two objects with implicit type and there no associations to
instantiate, Rational Rhapsody automatically creates a new, symmetric association.

566 User Guide

 Associations

Link features
The Features window enables you to change the features of a link, such as the association being
instantiated by the link.

The title bar is in the form:

Link: [end1 instance](end1 role name)-[end2 instance] (end2 role name)
For example, a(itsA)-b(itsB).

A link has the following features:

Name specifies the name of the link.

L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the link, if any. They are enclosed in guillemets, for
example «s1» and enable you to tag classes for documentation purposes. For information
on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Association specifies the association being instantiated by the link.

Rational Rhapsody allows you to specify a link without having to specify the association
being instantiated by the link. Until you specify the association, this field is set to
<Unspecified>.

If you select <New> from the list, Rational Rhapsody creates a new, symmetric
association based on the data (its name and multiplicity) for the link. Note that once you
specify an association for the link, you cannot change the role name or multiplicity for the
link (the corresponding fields of the Features window are unavailable).

To change the features of an association of which the link is an instantiation, you must
open the Features window of the association itself. Any changes you make to the
association are instantly applied to links that are instantiated from it.
End1 and End2 specifies the two ends of the link, including:
– Name means the name of the link.
– Multiplicity means the multiplicity of the link.
– Via Port means the port used by the link, if any. This is a read-only field.
Description describes the element. This field can include a hyperlink. For more
information, see Hyperlinks.

Rational Rhapsody 567

Object model diagrams

Link menu
In addition to the common operations (see Edit elements), the menu for links includes the
following options:

When you right-click a link, the menu contains the following options:

Select Link lists the available links in the model. For more information, see Referencing
links.
Select Association to instantiate lists the associations available in the model so you can
easily select one for the link to instantiate. For more information, see Mapping a link to an
association.
Show Labels specifies whether to display element labels in the diagram.

Note that if you select this option and the link instantiates an association, the link ends
will use the labels instead of the role names of the corresponding association ends.
Display Options determines whether the names and multiplicities of link ends are
displayed. For more information, see Displaying links.

Referencing links
To map a link line to an existing link in the model, right-click the link and select Select Link, as
shown in this example. This functionality is very useful when you have more than one link
between the same elements.

To reference an existing link, select it from the submenu.

Mapping a link to an association

To map a link line to an existing association in the model, right-click the link and select Select
Association to instantiate, as shown in this example.

568 User Guide

 Associations

To change the association, simply select a different association from the submenu. If you do this
and the Active Code View is active, the corresponding code updates to reflect the change.

Displaying links
By default, the names and multiplicities of link ends are not displayed. To change the display,
right-click the link and select Display Options.

Note
Although the Link Name field is available by default, the “generated” link name is not
shown on the diagram. However, if you change the name of the link, the new name will be
displayed in the diagram.
Enable (check) the fields you want displayed in the diagram.

Using the complete relations functionality

The following table shows the results of using the Complete Relations functionality with
associations, generalizations, dependencies, and links.

Completing relations
between these Results in...
elements...
Two classes Rational Rhapsody draws the
associations, generalizations, and
dependencies but not the links.
Two objects with implicit type Rational Rhapsody draws the
associations, generalizations,
dependencies, and links. If the link
instantiates an association, the link
is drawn, but the association is not.
Two objects with explicit type Rational Rhapsody draws only the
links.

For more information in the Complete Relations functionality, see Complete relations.

Rational Rhapsody 569

Object model diagrams

Code generation for links

The code for run-time connection of objects is based on links. The connection code is generated
when the following conditions are met:

Links are specified with an association.

The objects connected by the link has an owner (composite class or object) or are global
(both objects are owned by a package).

If the objects are parts of a composite, the link is owned by the composite. When the
objects are global, the link is owned by a package. Links across packages are initialized
by the component.
The package and objects for the link are in the scope of the generated component.
The CG::Component::InitializationScheme property for the component is set to
ByComponent for links across packages.
If more than one link exists between two objects over the same relation, Rational
Rhapsody arbitrarily chooses which link to instantiate. The packages that contain the
objects are given priority in this decision.

570 User Guide

 Associations

Populating one-to-many associations with objects

If you draw a one-to-many directed association between a class A and a class B, and create an
object of A and several objects of B, you can connect the objects with a link that instantiates the
association. The Rational Rhapsody-generated code for such a relationship creates a container
class for the one-to-many relationship in A, and creates objects of A and B. However, it does not
necessarily populate the container for A with the objects of B. When you model a relationship as
one-to-n, Rational Rhapsody instantiates n objects in the container. Rational Rhapsody populates
only associations with known multiplicity, and graphically shows when an association instance, or
link, actually exists and when it does not.

You can populate a one-to-many container by creating the objects in source code and adding them
to the container. However, you cannot model a generic one-to-many relationship and populate it
with an unknown number of diagrammatically modeled objects. Therefore, it is not possible to
populate a one-to-many relationship between classes drawn in one OMD with objects drawn in
another OMD.

Restrictions
Note the following limitations and restrictions:

Code generation for links across composite classes is not supported.

You cannot make a link when one or both sides of the relation are classes (as opposed to
objects).

Rational Rhapsody 571

Object model diagrams

Dependencies
A dependency exists when the implementation or functioning of one element (class or package)
requires the presence of another element. For example, if class C has an attribute a that is of class
D, there is a dependency from C to D.

In the UML, a dependency is a directed relationship from a client (or clients) to a supplier stating
that the client is dependent on, and affected by, the supplier. In other words, the client element
requires the presence and knowledge of the supplier element. The supplier element is independent
of, and unaffected by, the client element.

Dependency arrows
A dependency arrow is a dotted line with an arrow. You can draw a dependency arrow between
elements, or you can have one end attached and the other free. It can have a label, which you can
move freely. If a dependency arrow is drawn to or from an element, it is attached to the element;
the attached end moves with the attached border of the element.

Dependency arrows show that one thing depends on something else:

An object that is a (logical) instantiation of another

An object that creates or deletes another
Constraints attached to an element
A class that uses another class or package
A package that uses another package or class
You can create a dependency in a diagram or in the browser.

572 User Guide

 Dependencies

Drawing the dependency

To draw a dependency in the diagram:

1. Click the Dependency icon .

2. Click the dependent object.

3. Click the object on which it depends. This object also known as the provider.

Note that you can create more than one dependency between the same two elements. For example,
if you create one dependency from element X to element Y, the default name of the dependency is Y.
If you create a second dependency between the same two elements, the second dependency is
named Y_0 by default. To rename a dependency, do one of the following actions:

Open the Features window for the dependency, and type the new name in the Name field.
In the browser, left-click the dependency whose name you want to change, and type the
new name in the text box.

Creating the dependency in the browser

To create a dependency using the browser:

1. In the browser, right-click the element that depends on another element and then select
Add New > Dependency. The Add Dependency window opens.

2. Use the list to select the element on which the specified element depends.

Click the <<Select>> line to open a browsable tree of the entire project, as shown in
the following example.

Rational Rhapsody 573

Object model diagrams

3. Highlight the appropriate element, then click OK.

4. Rational Rhapsody creates the new dependency under the Dependency category for the
dependent element, with an open text box so you can easily rename the dependency.

5. If wanted, rename the dependency.

574 User Guide

 Dependencies

Dependency features
The Features window enables you to change the features of a dependency, including its name and
stereotype.

A dependency has the following features:

Name specifies the name of the dependency.

L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the dependency, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Depends On specifies the class or package that provides information to the dependency.
Description describes the dependency. This field can include a hyperlink. For more
information, see Hyperlinks.

Rational Rhapsody 575

Object model diagrams

Dependency menu
In addition to the common operations (see Edit elements), the menu for dependencies includes the
following options:

Display Options specifies how dependencies are displayed. The following figure shows
the display options for dependencies.
Select Dependency enables you to select a dependency. This functionality is useful when
you have more than one dependency between the same elements.

Constructive dependencies
Rational Rhapsody supports the dependency stereotypes «Send», «Usage», and «Friend».

Note
If a class has a dependency on another class that is outside the scope of the component,
Rational Rhapsody does not automatically generate an #include statement for the external
class. You must set the «Usage» stereotype and the <lang>_CG::Class::SpecInclude
property for the dependent class.
Stereotypes are shown between guillemets («..») and are attached to the dependency line in the
OMD, as shown in this example.

The Properties tab in the Features window enables you to define the UsageType property for the
dependency. This property determines how code is generated for dependencies to which a «Usage»
stereotype is attached. The possible values for the UsageType property are as follows:

Specification where an #include of the provider is generated in the specification file

for the dependent.
Implementation where an #include of the provider is generated in the implementation
file for the dependent.
Existence where a forward declaration of the provider is generated in the specification
file for the dependent.
For more information on stereotypes, see Stereotypes.

576 User Guide

 Actors

Actors
An actor is a “coherent set of roles that users of use cases play when interacting with these use
cases. An actor has one role for each use case with which it communicates.” (UML specification,
version 1.3) An actor is a type of class with limited behavior. As such, it can be shown in an OMD.

Creating an actor
To create an actor:

1. Click the Actor icon .

2. Click, or click-and-drag, in the diagram.

For a detailed explanation of actors, see Actors. Note that an actor has a Features window that is
very similar to that of a class; for more information about the Features window Creating classes.

The actor menu

In addition to the common operations (see Edit elements), the menu for actors includes the
following options:

New Statechart opens the statechart editor (see Statecharts)

New Activity Diagram opens the activity diagram editor (see Activity diagrams)
New Attribute opens the Attribute window (see Defining the attributes of a class)
New Operation opens the Operation window (see Class operations)
Generate generates code for the actor (see Basic code generation concepts)
Edit Code opens the actor code in a text editor (see Editing Code)
Roundtrip where roundtrips edits made to generated code back into the model (see The
roundtripping process)
Open Main Diagram opens the main diagram for the actor
Display Options opens the Display Options window
Cut removes the actor from the view and saves it to the clipboard
Copy saves a copy of the actor to the clipboard, while leaving it in the view

Rational Rhapsody 577

Object model diagrams

Flows and flowitems

Flows and flowitems provide a mechanism for specifying exchange of information between
system elements at a high level of abstraction. This functionality enables you to describe the flow
of data and commands within a system at a very early stage, before committing to a specific
design. As the system specification evolves, you can refine the abstraction to relate to the concrete
implementation.

Flows can convey flowitems, classes, types, events, attributes and variables, parts and objects, and
relations. You can draw flows between the following elements:

Actors
Classes
Components
Nodes
Objects
Packages
Parts
Ports
Use cases
You can add flows to all of the static diagrams supported by Rational Rhapsody.

578 User Guide

 Flows and flowitems

The flows in this object model diagram show the black-box representation of an air conditioning
unit and the actors that interact with it. It includes the information that is passed either from an
actor to the AC unit or from the AC unit to an actor.

Creating a flow
Every static diagram toolbar includes an Flow tool, which is drawn like a link. Static (or
structural) diagrams include object model diagrams, structure diagrams, use case diagrams,
component diagrams, and deployment diagrams.

To create a flow:

1. In the Diagram Tools, click the Flow icon or choose Edit > Add New > Relations
> Flow.

Note: Add New > Relations is the default menu command structure in Rational
Rhapsody. It can be changed by users. This topic assumes that all defaults are
in place.
2. In the diagram, click near the first object to anchor the flow.

Rational Rhapsody 579

Object model diagrams

3. Click to place the end of the flow.

4. In the edit box, type the element conveyed by the flow, then press Enter.
By default, a flow is displayed as a green, dashed arrow with the keyword «flow» underneath it.

To suppress the «flow» keyword, open the Display Options window and disable the <<flow>>
keyword check box. You can also control the display of the <<flow>> keyword for new flows by
setting the <Static diagram>::Flow::flowKeyword Boolean property.

The flows and flowitems are both displayed in the browser, as shown in the following example.

580 User Guide

 Flows and flowitems

Features of a flow
The Features window enables you to change the features a flow, such as its name or flow ends. A
flow has the following features:

Name specifies the name of the flow. By default, the flow is named using the following
convention:

<source>_<target>[_###]

In this convention, the source and target are end1 and end2 of the flow, based on the
direction (end1 is the source in bidirectional flows as well as flows from end1 to end2);
_### specifies additional numbering when the name is already used.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the flow, if any. They are enclosed in guillemets, for
example «s1» and enable you to tag classes for documentation purposes. For information
on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Flow Ends specifies how the information travels, from the source (End1) to the target
(End2). To change either end, use the pull-down list to select a new source or target from
the selection tree.
Direction specifies the direction in which the information flows. To invert the flow, or to
make it bidirectional, use the appropriate value from the
pull-down list.
Description describes the flow. This field can include a hyperlink. For more information,
see Hyperlinks.

Rational Rhapsody 581

Object model diagrams

Conveyed information
All the information elements that are conveyed on the flow are listed on the Flow Items tab, as
shown in this example.

An information element can be any Flowitem, as well as elements that can realize a flowitem
(classes, events, types, attributes and variables, parts and objects, and relations).

This tab enables you to perform the following tasks on information elements:

Add a new information element.

Add an existing information element.
Remove an information element.
View the features of an information element.
For detailed information on manipulating information elements, see Flowitems.

582 User Guide

 Flows and flowitems

Note that you can specify multiple information elements using a comma-separated list. For
example, in the OMD the flow from the AC unit to the Display actor contains two information
elements: the DisplayInfo flowitem and the evStateChg event. The following figure shows the
corresponding Flow Items tab.

Flow menu
In addition to the common operations (see Edit elements), the menu for flows includes the
following options:

Display Options opens the Display options window for the flow.
Select Information Flow provides a list of the flows already defined between these ends
so you can easily reuse flows in your model.

Flowitems
A flowitem is an abstraction of all kinds of information that can be exchanged between objects. It
does not specify the structure, type, or nature of the represented data. You provide details about the
information being passed by defining the classifiers that are represented by the flowitem.

Flowitems can be decomposed into more specific flowitems. This enables you to start in a very
high level of abstraction and gradually refine it by representing the flowitem with more specific
items.

Rational Rhapsody 583

Object model diagrams

A flowitem can represent either pure data, data instantiation, or commands (events). Flowitems
can represent the following elements:

Classes
Types
Events
Other information items
Attributes and variables
Parts and objects
Relations

Flowitem features
To view the features of a particular information element, double-click the element in the list on the
Flow Items tab for the flow. The corresponding Features window opens.

A flowitem has the following features:

Name specifies the name of the flowitem.

L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the flowitem, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Represented lists all the information elements that are represented by this flowitem. In
this example, the DisplayInfo flowitem represents the ACInfo class.
Description describes the information element. This field can include a hyperlink. For
more information, see Hyperlinks.

584 User Guide

 Flows and flowitems

Adding a new information element

To add a new information element to the flow:

1. To create a new attribute, either click the <Add> row in the list of information elements,
or click the New icon in the upper, right corner of the window and select the appropriate
element from the list.

The new element is added to the list and its Features window automatically opens.

2. Set the new values for the element.

3. Click OK twice.

Adding an existing information element to the flow

To add an existing information element to the flow:

1. On the Flow Items tab for the flow, highlight the <Add> row and select the <Select>
option in the menu.

2. Expand each subcategory as needed to select the information element from the tree, then
click OK.

3. You return to the Flow Items tab, where the specified information element now displays
in the list of elements.

4. Click OK.

Rational Rhapsody 585

Object model diagrams

Embedded flows
In SysML notation, flows can be embedded in links. Rational Rhapsody allows you to use this
notation in object model diagrams.

Creating an embedded flow

To add a flow to a link:

1. Click the Flow icon .

2. Click the link to which you want the flow added.

Once the flow is created, it has the same features as an ordinary flow element, representing the
flow of data between the two objects that are linked. Visually, the flow is displayed on top of the
link, and it is depicted by an arrow.

To select the embedded flow element, double-click the arrow.

To move the embedded flow diagram element, drag the arrow to a new position on the link.

Changing the flow direction

To change the flow direction, right-click the flow, and then select Flip Flow Direction.

Changing display options for embedded flows

For an ordinary flow diagram element, the <flow> keyword is displayed alongside the flow
element. To display this for embedded flows:

1. Select the flow.

2. Right-click and select Display Options.

3. Select <flow> keyword or Stereotype.

4. Click OK.

Restrictions
Note the following restrictions and limitations:

Flows cannot be animated.

There is no code generation for flows.

586 User Guide

 Files

Files
Rational Rhapsody Developer for C allows you to create model elements that represent files. A file
is a graphical representation of a specification (.h) or implementation (.c) source file. This new
model element enables you to use functional modeling and take advantage of the capabilities of
Rational Rhapsody (modeling, execution, code generation, and reverse engineering), without
radically changing the existing files.

Note
Files are not the same as the file functionality in components that existed in previous
versions of Rational Rhapsody. To differentiate between the two, the new file is called File
in Package and the old file element is called File in Component. A File in Component
includes only references to primary model elements (package, class, and object) and shows
their mapping to physical files during code generation.
A file element can include variables, functions, dependencies, types, parts, aggregate classes, and
other model elements. However, nested files are not allowed.

Rational Rhapsody supports the following modeling behavior for files:

You can drag files onto object model diagrams and structure diagrams.
If you use the FunctionalC profile, then the File tool is available in the Diagram Tools for
object model diagrams and structure diagrams.
You can drag files onto a sequence diagram, or realize instance lines as files.
A file can have a statechart or activity diagram.
Files are implicit and always have a multiplicity of 1.
Files are listed in the component scope and the initialization tree of a configuration. They
have influence in the initialization tree only in the case of a Derived scope.
Files can be defined as separate units, and can have configuration management performed
on them. For more information, see Using project units.
Files can be owned by packages only.

Rational Rhapsody 587

Object model diagrams

Creating a file
To create a file element:

1. Click the File icon in the Diagram Tools, or select Edit > Add New > File.

2. Click, or click-and-drag, in the drawing area. By default, files are named file_n, where n
is an integer greater than or equal to 0.

3. Edit the default name, then press Enter.

The file is shown as a box-like element in the diagram, with the «File» notation in the top of the
box.

The following figure shows an OMD that contains files.

You can specify whether file variables and functions are displayed in diagrams using the Display
Options feature. The Display Options window for files is identical to that for classes, except the
tab names are Variables instead of Attributes and Functions instead of Operations. For more
information, see Display option settings.

588 User Guide

 Files

Files can be owned by packages only. File elements are listed in the browser under the Files
category under the owning package, as shown in this example.

Rational Rhapsody 589

Object model diagrams

File features
The Features window enables you to change the features of an file, including its name, stereotype,
and main diagram. The following figure shows the Features window for a file.

The General tab for a file is very similar to that of an object (see Object features), with the
following differences:

The Type, Initialization, Multiplicity, and Relation to whole fields are unavailable.
Multiplicity has no meaning with files, because a file is simply a file (not an object that
can be instantiated). Similarly, a file cannot be an instantiation of a class (it is always
implicit).
The Path field is a read-only field that displays the path to the file. Click the icon to
navigate directly to the specified source file.

The Variables tab

The Variables tab of the file Features window enables you to add, edit, or remove variables from
the file. It contains a list of all the variables belonging to the file. The following figure shows the
Variables tab.

590 User Guide

 Files

The Functions tab

The Functions tab of the file Features window enables you to add, edit, or remove functions from
the file. It contains a list of all the functions defined in the file. The following figure shows the
Functions tab.

Rational Rhapsody 591

Object model diagrams

Converting files
You can easily convert a file to an object or vice versa by simply highlighting the object in the
browser, then selecting Change to and the intended result.

To convert a file to a class:

1. Highlight the file in the browser, right-click and then select Change to > Object. The file
changes to an object and moves to the Objects category in the browser.

2. Highlight the object in the browser, right-click and then select Expose Class. This create a
new class with the name <object> class. It contains all of the content of the copied
object including the attributes, operations, and statechart. This option is only available for
an implicit object.

Note the following information:

If you are trying to convert an object to a file and there are aggregates that are not allowed
for files, Rational Rhapsody issues a warning message.
Objects that are owned by another class or object cannot be converted to files.
When the element has been converted, the graphical representations change in the diagrams and
the converted element is moved to the appropriate category in the browser.

For information on changing the order of files, see Editing the declaration order of objects.

Associations and dependencies

Files can be connected through associations or «Usage» dependencies. As standard practice, you
should use associations.

For example, consider the files shown in the following figure.

Because these files are connected through bi-directional association, File1 can call doFunction()
directly from an operation or action on behavior.

592 User Guide

 Files

Code generation for files

During code generation, files produce full production code, including behavioral code. In terms of
their modeling properties, modeled files are similar to implicit singleton objects.

For an active or a reactive file, Rational Rhapsody generates a public, implicit object (singleton)
that uses the active or reactive functionality. The name of the singleton is the name of the file.

Note
The singleton instance is defined in the implementation source file, not in the package
source file.
For a variable with a Constant modifier, Rhapsody generates a #define
statement. For example:
#define MAX 66
The following table shows the differences between code generation of an object and a file.

Model Element File Code Object Code

Data member (attribute, A global variable A member in the singleton
association, or object) struct
Function name1 The function name pattern is The name pattern for public
<Function>. functions is
<Singleton>_<function
>.
The pattern for private
functions is <Function>.
Function signature The me argument is generated when The same.
required to comply with the signature of
framework callback functions (for reactive
behavior).
Initialization Variables and associations are initialized Done in the initialize
directly in the definition. For example: function.
int x=5;
Objects are initialized in a generated Init
function.
Type name The name pattern for types (regardless of The name pattern for public
visibility) is <Type>. types is
<Singleton>_type.
The name pattern for private
functions is <Type>.
The name pattern can be
configured using the
properties
<lang>_CG::Type::Publ
icName and PrivateName.

Rational Rhapsody 593

Object model diagrams

Model Element File Code Object Code

Visibility Public members are declared as extern Member visibility is ignored;
in the specification (.h) file and defined in the visibility is a result of the
the implementation (.c) file. visibility of the struct.
For example: For example:
extern int volume; struct Ob_t {
Private members are declared and int volume;
defined in the implementation file as };
static.

For example:
static int volume;
Auto-generated
Initialization and Only algorithmic initialization is done in the Any initialization is done in
cleanup initialization method (creating parts; the Init method.
initializing links, behavior, and animation). Init and Cleanup
The initialization and cleanup methods are methods are generated by
created only when needed. default.
The name of the initialization function is
<file>_Init; the cleanup function is
<file>_Cleanup.
Framework data Rational Rhapsody generates a Framework members are
members designated struct that holds only the generated as part of the
framework members, and a single object struct declaration.
instance of the struct named <file>.
The struct name is <file>_t.
For example:
struct Motor_t {
RiCReactive ric_reactive;
}
Call framework Framework operations on the file are Framework operations on
operations called using the file. the singleton are called
For example: passing the singleton
instance.
CGEN(Motor, ev());
For example:
CGEN(Motor,ev());
Statechart data Statechart data members are generated Statechart data members
members as attributes of the generated structure. are generated as part of the
For example: struct.
struct F_t {
...
enum F_Enum {
F_RiCNonState=0,
F_ready=1}
F_EnumVar;
int rootState_subState;
int rootState_active;
};

594 User Guide

 Files

Model Element File Code Object Code

Statechart function Public statechart functions are generated Use the same naming
names using the prefix <file>_. convention as any other
For example: operation.
myFile_sIN()
1. You can configure the name pattern for functions (for files, objects, and other elements)
using the properties <lang>_CG::Operation::PublicName and PrivateName.

Files with other tools

The following table lists the effect of files on both Rational Rhapsody and third-party tools.

Tool Description
COM API Files are supported by the COM API via the IRPFile and
IRPModule interfaces
Complete Relation When you select Layout > Complete Relations, files and
their relations are part of the information added to the
diagram.
For more information on this functionality, see Complete
relations.
DiffMerge Files are included in difference and merge operations,
completely separate from objects.
Java API Files are supported by the Java API
Populate Diagram Files and their relations are fully supported
References If you use the References functionality for a file, the tool lists
the owning package for the file and the diagrams in which the
specified file displays. When you select a diagram from the
returned list, the file is highlighted in the diagram.
For more information on this functionality, see Searching in
the model.
Report on model In a report, the objects and files in the package are listed in
separate groups in that order.
For more information on this reporting tool, see Reports.
Search in model You can search for files in the model and select their type
from the list of possible types. When selected, the file is
highlighted in the browser.
For more information on this functionality, see Searching in
the model.
XMI Toolkit When you export a file to XMI, it is converted to an object with
a «File» stereotype. Files imported from XMI are imported
into Rational Rhapsody as files.

Rational Rhapsody 595

Object model diagrams

Attributes, operations, variables, functions, and types

In object model diagrams, attributes and operations are contained in classes. Therefore, they are
not included as separate items in the Diagram Tools. Similarly, variables, functions, and types are
not included in the Diagram Tools.

There might, however, be situations where you will want to show a higher level of detail and
include attributes, operations, variables, functions, or types as individual diagram elements.
Rational Rhapsody provides a solution for these situations by allowing you to drag these elements
from the browser to an OMD diagram

Adding details to the object model diagram

To add an attribute, operation, variable, function, or type to the diagram:

1. Select the relevant item in the browser.

2. Drag the item to the diagram window.

Note
Rational Rhapsody allows these types of elements to be dragged from the browser to any of
the static diagrams, not just object model diagrams.
When an item of this type is added to a diagram, the graphic element will display by default, the
element name, the stereotype applied (if there is one) or the metatype of the element, and the
associated image (if one has been defined).

Like all diagram elements, the Features window for these elements can be opened by double-
clicking on the element in the diagram.

The connectors provided in the Diagram Tools can be used to connect individual elements of
these types if the connection is semantically logical.

Once an element has been added to a diagram, the element can be added to a container element by
dragging the element into the container element, for example, an attribute on the diagram can be
dragged into a class.

Note
Graphic representations for these types of items can only be created by dragging them from
the browser to the diagram. There is no API equivalent for this action.

596 User Guide

 Attributes, operations, variables, functions, and types

Flow ports
Flow ports allow you to represent the flow of data between objects in an object model diagram,
without defining events and operations. Flow ports can be added to objects and classes in object
model diagrams. They allow you to update an attribute in one object automatically when an
attribute of the same type in another object changes its value.

Note
Flow ports are not supported in Rational Rhapsody in J.

Adding a flow port

To add a flow port, right-click the object or class and then select Ports > New Flowport.

The method used for specifying the data that is to be sent/received via the flow port depends upon
the type of flow port used - atomic or non-atomic. Non-atomic flow ports can only be used if your
model uses the SysML profile. The following sections describe these two types of flow ports.

Atomic flow ports

Atomic flow ports can be input or output flow ports, but not bidirectional. To specify the flow
direction, open the Features window for the flow port and select the appropriate direction.

You specify the attribute that is to be sent/received via the flow port by giving the attribute and
flow port the same name. If no attribute name matches the name of the flow port, a warning to this
effect will be issued during code generation.

Atomic flow ports allow the flow of only a single primitive attribute.

When connecting two atomic flow ports, you have to make sure that one is an input flow port and
one is an output flow port. The type of the attribute in the sending and receiving objects must
match.

To connect two flow ports, use the Link connector.

Rational Rhapsody 597

Object model diagrams

Defining non-atomic flow ports

Non-atomic flow ports are available only in models that use the SysML profile.

Non-atomic flow ports can transfer a list of flow properties (a flow specification), which can be
made up of flow properties of different types. For each flow property in the list, you indicate the
direction of the flow. (Non-atomic flow ports are bi-directional.)

To define the flow properties to be sent/received via the flow port:

1. Create a flow specification.

2. Add flow properties to the flow specification. This can be done using the relevant browser
context menu, or directly on the FlowProperties tab of the Features window for the flow
specification. You can also use drag-and-drop in the browser to add existing flow
properties to the flow specification. (If you want to use an existing attribute, you can
convert the attribute to a flow property by selecting Change To > FlowProperty from the
attribute context menu.)

3. For each of the flow properties defined, specify the direction.

4. Create two objects and add a flow port to each.

5. In the Features window for each of the two flow ports (the sending and receiving), set the
Type to the name of the flow specification you created previously.

6. For one of the flow ports, open the Features window and select the Reversed check box
on the General tab

7. Connect the two flow ports with a link.

Updating attribute values

To have the value of an attribute updated when the attribute on the other end of flow is updated,
you must use the function setflowportname, for example, if you have a flow port called x, you
would call setX(5).

When this function is called, there is also an event generated called chflowportname. In our
example, it would be chX. In order to be able to react to this event, you must define an event with
this name in your model.

For both of these functions, the first letter of the flow port name is upper-case even if the actual
name of the flow port begins with a lower-case letter.

Note
For details regarding the use of flow ports when importing Simulink models, see Integrating
Simulink components.

598 User Guide

 External elements

External elements
Rational Rhapsody enables you to visualize frozen legacy code or edit external code as external
elements. This external code is code that is developed and maintained outside of Rational
Rhapsody. This code will not be regenerated by Rational Rhapsody, but will participate in code
generation of Rational Rhapsody models that interact or interface with this external code so, for
example, the appropriate #include statement is generated. This functionality provides easy
modeling with code written outside of Rational Rhapsody, and a better understanding of a proven
system.

Rational Rhapsody supports the following functionality for external elements:

Reverse engineering can import elements as external.

Reverse engineering populates the model with enough information to:
– Model external elements in the model.
– Enable you to open the source of the external elements, even if the element is
not included in the scope of the active component.
Rational Rhapsody generates the correct #include for references to external elements.
Elements inherit their externality from the parent. For example, if a package is external, all
its aggregates are also external.
You can add external elements to component files to define the exact location of the source
code.
Rational Rhapsody displays external elements in the scope tree of the component.
There are two ways to create external elements:

By reverse engineering the files

By modeling

Rational Rhapsody 599

Object model diagrams

Reverse engineering
When creating external elements using reverse engineering, the preferred method depends on
whether the code is frozen legacy code or the code is still being modified.

Reverse engineering a single iteration

For legacy code or a library that will not change, it is appropriate to model external code for
referencing, without regenerating it.

To use reverse engineering to create the external elements a single time:

1. Create a new model or open an existing one.

2. Add a new component for the reverse engineered, external code.

3. Set your new component (created in the previous step) to be the active component
(right-click it in the Rational Rhapsody browser and select Set as Active Component).

4. Choose Tools > Reverse Engineering to open the Reverse Engineering window.

5. Specify the files or folders you want to reverse engineer.

6. Click the Advanced button to open the Reverse Engineering Options window.

7. On the Mapping tab, specify the following settings:

a. Select the Visualization Only (Import as External) check box.

The following figure shows an example for Rational Rhapsody in C.

600 User Guide

 External elements

b. For Rational Rhapsody in C, select the Files radio button (default) in the Modeling
Policy area; for the other languages, select the appropriate option for your situation.
The availability of these radio buttons might depend on whether you select the
Visualization Only (Import as External) check box.

8. Set the other reverse engineering options as appropriate for your model. (For more
information on the available options on the Mapping tab, see Mapping classes to types
and packages.)

9. Click OK.

10. Click the Start button on the Reverse Engineering window.The specified files are
imported into Rational Rhapsody as external elements.

As a result of the import:

The imported elements are added to the scope of the configuration.

All the imported packages have the property CG::Package::UseAsExternal set
to Checked.
The Include Path or Directory of the Features window for the configuration (in
the example, ExternalComponent) is set to the correct include path.

Rational Rhapsody 601

Object model diagrams

In Rational Rhapsody in C, when the Directory is a Package radio button is

selected, the C_CG::Package::GenerateDirectory property is set to Checked
for the configuration.

Note that external elements include a special icon in the upper, right corner of the
regular icon, as shown in this example.

11. Verify the import to make sure the implementation and specification files are named
correctly, the correct folders were created, and so on. Make any necessary changes.

12. Set the original component to active.

13. For the original component, create a dependency with a «Usage» stereotype to the
ExternalComponent.

14. Make sure that the external elements are included in the scope of the ExternalComponent
only.

602 User Guide

 External elements

Reverse engineering multiple iterations

Suppose you want to model external code for referencing, without regenerating it (but the external
code might change and the external element should be updated according to the changes in the
code).

Set up your model as follows:

1. Complete the steps in the previous procedure (see Reverse engineering) to create a new
external model (for example, ExternalModel).

2. Save your model, then close it.

3. Open a new, development model.

4. Choose File > Add to Model, then select the external model. Select As Reference and
select all the top-most packages and the component (ExternalModel). The elements are
imported as read-only (RO).

5. Create a dependency with a «Usage» stereotype to the ExternalModel.

To synchronize the code changes:

1. Open the external model.

2. Update the reverse engineering options as needed to include the code modifications (such
as including new folders), and then click Import.
3. Close the external model.

4. Open the development model.

5. Update the model according to the changes in the external model:

a. Remove references to elements deleted from the external model.

b. Update references to renamed elements from the external model (they become
unresolved).

c. New elements are simply added to the model.

Rational Rhapsody 603

Object model diagrams

Creating external elements in pre-V5.2 models

To add external elements to models created before Version 5.2:

1. Unoverride the following properties:

CG::Configuration::StrictExternalElementsGeneration
CG::Component::SupportExternalElementsInScope
These properties are automatically overridden by Rational Rhapsody when you load
an older model.

2. Follow the procedure described in Reverse engineering a single iteration.

604 User Guide

 External elements

External elements created by modeling

Alternatively, you can add external elements to the model manually. This option is used when
there are very few elements to be modeled as external.

There are two ways to model the elements manually:

Using rapid external modeling

Using the component model

Using rapid external modeling

To model the elements manually using rapid external modeling:

1. Open an existing model or create a new one.

2. Create the external elements:

Create the new element to be referenced.

Set its CG::Class::UseAsExternal property to Checked.
Set its CG::Class::FileName property to the value expected in the #include. For
example, MySubsystem\C.
3. Add the rest of the path to the Include Path field of the component. In the example, this
would be C:\MyProjects\Project1.

4. Add the external elements to the scope of the component.

5. Add relations to the external elements (for more information, see External element code
access).

Rational Rhapsody 605

Object model diagrams

Using the component model

To model the elements manually using the component model:

1. Open an existing model or create a new one.

2. Add a new component for the external elements (for example, ExternalComponent).

3. Set the scope of the component to Selected Elements.

4. Create a package that will contain all the external elements, and set its
CG::Package::UseAsExternal property to Checked.

Note: This step is optional; you can also add external elements to existing packages.
5. Add the package that contains the external elements to the scope of the external
component. Make sure that the package is not included in the scope of other components.

6. Create a new element that will be referenced in the package.

7. Provide the following information about the source files of the external elements:

a. Create a hierarchy of packages as needed for the proper #include path. For example,
suppose you want reference class C, which is defined in
C:\MyProjects\Project1\MySubsystem\C.h; you would create the package
MySubsystem.

b. Add a file with the necessary name to the folder and map the external element to it.
You do not need to do this if the external element has the same name as the file.
c. Create a usage dependency to the external component.

8. Add relations to the external elements (for more information, see External element code
access).

In the generated files, the following #include is generated for the example element:
#include <MySubsystem\C.h>

606 User Guide

 External elements

Creating a shortcut for Rational Rhapsody Developer for C

In Rational Rhapsody Developer for C, you can use the following shortcut in place of Steps 2–7 in
the previous procedure:

1. Create a hierarchy of packages as needed for the proper #include path.

For example, suppose you want reference class C, which is defined in

C:\MyProjects\Project1\MySubsystem\C.h; you would create the package
MySubsystem.

2. Set the CG::Package::UseAsExternal property for the top-most package to Checked.

3. Create the appropriate files (for more information, see Creating a file). Continuing the
example, you would simply create the file C.

4. Create a new element that will be referenced in the file.

5. Add the rest of the path to the Include Path field of the component. In the example, this
would be C:\MyProjects\Project1.
6. Set the property C_CG::Package::GenerateDirectory to Checked for the component.

Rational Rhapsody 607

Object model diagrams

Converting external elements

You can convert external elements so they are no longer external (and therefore include them in
code generation). This functionality enables you to gradually move code that was developed
outside of Rational Rhapsody to an application being developed using Rational Rhapsody.

To convert all the external elements at once:

1. Open the model.

2. Change the following properties:

Unoverride the property CG::Package::UseAsExternal for the top-most

packages.
Unoverride the properties Generate and AddToMakefile (under CG::File) for
the top-most folders in the external element component.
3. Add the packages and classes to the scope of the development component and remove the
packages and classes from the external element component.
4. Delete the external component.

5. Generate and build the code.

6. Continue development in Rational Rhapsody as usual.

To convert specified external elements:

1. Create a new package for the converted elements (for example, RedesignPackage).

2. Add the new package to the scope of the development component.

3. Move one class or file from the external package to the RedesignPackage.

4. Generate, build, and test the code. Repeat as necessary.

5. Repeat Steps 3 and 4 for as many classes or files as you want to convert.

6. Continue development in Rational Rhapsody as usual.

608 User Guide

 External elements

Viewing the path to the source file

The Features window for an external file in Rational Rhapsody in C includes a new field, Path,
which shows the full path to the specification source file. The path is read-only, but you can copy
it.

The following figure shows the updated window.

Click the icon to navigate directly to the specified source file.

Rational Rhapsody 609

Object model diagrams

External element code access

To access the code in the external files, create relations to them (such as dependencies with
«Usage» stereotypes, generalizations, associations, and so on). Note that the resultant source code
will automatically contain the correct #include statements for the external elements.

In the Features window for the configuration, set the scope to Selected Elements, and verify that
the external files are not checked.

When you generate code that includes relations to external elements:

Dependencies are converted to #includes.

Generalizations are converted to inheritance and #include.
Associations are converted to data members and #includes.
Types are converted to type and #include.
Objects and parts are instantiated.
Once you have created the external elements, you can edit the code using the Edit menu, edit
options in the menu, or active code view window, just as you do for any Rational Rhapsody code.

Adding source files to the build

To add the source files of an external element to the build:

1. Add the component file that contains the mapping of the necessary external elements to
the component.

2. Set the property CG::File::Generate to Cleared.

3. Set the property CG::File::AddToMakefile to Checked.

610 User Guide

 External elements

Code generation for external elements

The following table lists how Rational Rhapsody generates code for external elements.

Element Type Description

Package The code generator does not generate code for an external package.
However, you can map the package to a file or folder for a component
(and then relate it to a file or directory). You can include the package
in the component scope.
During code generation, a relation to a package is converted an
#include to a file, if the package is mapped to a file for the
component.
Class, object, or file The code generator does not generate code for an external class,
object, or file.
During code generation, a relation to a class, object, or file is
converted to an #include or a forward declaration.
Type The code generator does not generate code for an external type. A
relation to a type is converted to an #include of its parent.
File (component) A file is external if all its elements are external.
If the CG::File::Generate property for a file is set to Cleared,
the file becomes external and code is not generated for it.
To include a file in the build, set its CG::File::AddToMakefile
property to Checked.

Code generation for relations

During code generation, Rational Rhapsody generates either an #include or a forward declaration
for a relation in the source file of the dependent element.

Forward declaration (class)

If a dependency has a «Usage» stereotype and the CG::Dependency::UsageType property is set to
Existence, it is generated as a forward declaration. For example:

class ExternalClass;

Rational Rhapsody 611

Object model diagrams

#includes for a class, object, or file

External dependencies (dependencies with a «Usage» stereotype and the
CG::Dependency::UsageType property set to Specification/Implementation) and implicit
dependencies (such as associations and generalizations) are generated as forward declarations and
#include statements.

To generate a local #include statement (for example, #include <C.h>), set the property
CG::File::IncludeScheme to LocalOnly.

To generate a relative #include statement (for example, #include <MySubsystem\C.h>), set the
CG::File::IncludeScheme to RelativeToConfiguration.

You can also use the C_CG/CPP_CG/JAVA_CG::Package::GenerateDirectory and CG::Class/

Package::FileName properties to set relative paths. See the definition of this property in the
Features window.

Limitations
Note the following restrictions and behavior of external elements:

External elements are not animated; they behave like the system border.
Changes in the source files of external elements are not roundtripped. If necessary, use
reverse engineering to update external elements.
Only the following elements can be external: class, implicit object or file, package, and
type. Components, folders, variables, and functions cannot be external.
You cannot use Add to Model to add an external element as a unit. However, you can add
the unit under another name, and then set that unit to be external.

612 User Guide

 Implementation of the base classes

Implementation of the base classes

In Rational Rhapsody Developer for C++ and for Java, you can easily convey model elements
defined at the interface level to the implementing class level. Using this functionality, classes
automatically realize the implementing interfaces and help you synchronize the changes in the
interface to the realizing classes.

There are two ways to start this functionality: implicitly and explicitly.

Implicit invocation
When you connect two classes with a generalization realization, the base classes are implemented
implicitly. However, a generalization will not trigger base class implementation in the following
cases:

Inheritance between two COM interfaces

Inheritance between two CORBA interfaces
Inheritance between two Java interfaces
If there are no operations or attributes to be overridden because of the current action, the
Implement Base Classes window is not displayed.

Rational Rhapsody 613

Object model diagrams

Explicit invocation
To access this functionality explicitly, in the browser or OMD, right-click a class and select
Implement Base Classes.

The Implement Base Classes window opens, as shown in this example.

Implement base classes window

This window provides a tree-like view of all the interfaces (including methods, attributes, and
stereotypes) that can be implemented by the class.

The window contains three filters to control the contents of the tree view:

Required displays the operations that must be implemented.

Optional displays the operations that can be implemented. By default, Rational Rhapsody
displays the required and optional operations.
Implemented displays the operations that are already implemented.

614 User Guide

 Implementation of the base classes

Base class tree view

Depending on the base class, Rational Rhapsody displays different items in the tree view. The
following table shows which items are displayed.

Base Class Items Displayed in the Tree View

C++ class All virtuals and pure virtuals. You must implement the pure
virtual methods.
Java class or Java interface All the methods. You must implement the interfaces. The
GUI takes into account the “final” option for Java methods
and classes.
COM interface All methods and attributes.
CORBA interface All methods.

Rational Rhapsody uses the following colors to differentiate the different method types:

Blue denotes a virtual method.

Bold, blue denotes an abstract method.
Gray denotes a method that has already been implemented.
If you try to open the Implement Base Classes functionality for a read-only class, Rational
Rhapsody displays a warning message informing you that the class cannot be modified. However,
the Implement Base Classes window opens in read-only mode so you can analyze the class. You
can view the code by selecting Edit Code, but the OK button will be disabled.

Rational Rhapsody 615

Object model diagrams

Editing the implementation code

To change the implementation code for an operation:

1. Select the operation in the tree view.

2. Click the Edit Code button. Rational Rhapsody displays the code in the default text editor.

3. Type in the new implementation code in the text box.

4. Click OK.

Note that if you try to edit code for an operation that has already been implemented, the text editor
displays the implementation code in read-only mode.

When you edit the implementation code, Rational Rhapsody overlays a red icon in the upper, left
corner of the class icon in the tree view, as shown in this example.

For more information on the internal code editor and its properties, see The Internal code editor.

Controlling the display of the window

The Automatically show this window check box controls whether the window is displayed on
implicit requests. By default, this check box is unavailable, so the window is displayed only when
you explicitly open it.

If you select this check box, Rational Rhapsody writes the following line to the [General] section
of the rhapsody.ini file:
ImplementBaseClasses=TRUE
If wanted, you can add this line directly to the rhapsody.ini file to automatically display the
window.

616 User Guide

 Implementation of the base classes

Realizing the elements

To realize an element, select it and click OK.

For example, suppose you want to implement the tune operation. In the window, select tune, then
click OK.

The PllTuner class implements the tune operation and displays it in the browser. If you select
Implement Base Classes for the PllTuner class again, the tune operation is no longer listed as a
required or optional element. Click Implemented to see that the tune operation was implemented
and is now displayed in gray, as shown in this example.

Rational Rhapsody 617

Object model diagrams

If an element has been implemented (it displays in gray in the tree and is checked), you cannot
uncheck (“unrealize”) it.

Note
If you choose Undo, Rational Rhapsody unimplements all the implemented classes, not just
the last one, because the implementation is viewed as a single, atomic operation. For
example, if you implement five elements during one operation, then select Undo, all five
are removed.

Namespace containment
Rational Rhapsody allows you to display namespace containment in object model diagrams. This
type of notation is also referred to as “alternative membership notation.” It depicts the hierarchical
relationship between elements and the element that contains them, for example:

requirements that contain other requirements

packages that contain classes
classes that contain other classes
The following screen captures illustrate the use of this notation.

618 User Guide

 Implementation of the base classes

Property that controls display of namespace containment

The display of namespace containment is controlled by the boolean property
ObjectModelGe:ClassDiagram:TreeContainmentStyle, which can be set at the diagram,
package, or project level. Namespace containment is displayed when the property is set to
Checked.

The default value of the property is Cleared. However, in the SysML profile the default value of
the property is Checked.

Displaying namespace containment

To display namespace containment in a diagram:

1. Drag the “container” element and the “contained” elements to the diagram.

2. From the menu, select Layout > Complete Relations > All

The hierarchical relationship between the elements will be depicted in the diagram.

Alternatively, you can select the Populate Diagram check box when creating a new diagram. If
you then select elements that have a hierarchical relationship, the diagram created will display the
namespace containment for the elements.

Note
There is no drawing tool to manually draw this type of relationship on the canvas.
Containment relationships between elements can only be displayed automatically based on
existing relationships, using one of the methods described above.

Rational Rhapsody 619

Object model diagrams

620 User Guide

 Activity diagrams

Activity diagrams specify a workflow, or process, for classes, use cases, and operations. As
opposed to statecharts, activity diagrams are preferable when behavior is not event driven. A class
(use case/operation) can have either an activity diagram or a statechart, but not both. However, a
class, object, or use case might have more than one activity diagram with one of the diagrams
designated as the main behavior.

Note
It is possible to change the main behavior between different activities within the same
classifier.

Activity diagram features

One useful application of activity diagrams is in the definition of algorithms. Algorithms are
essentially decompositions of functions into smaller functions that specify the activities
encompassed within a given process.

Note
Sequence diagrams can show algorithms of execution within objects, but activity diagrams
are more useful for this purpose because they are better at showing concurrency.
Activity diagrams have several elements in common with statecharts, including start and end
activities, forks, joins, guards, and states (called actions). Unlike statecharts, activity diagrams
have the following elements:

Decision points show branching points in the program flow based on guard conditions.
Actions represent function invocations with a single exit activity flow taken when the
function completes. It is not necessary for all actions to be within the same object.
Action blocks represent compound actions that can be decomposed into actions.
Subactivities represent nested activity diagrams.
Object nodes represents an object passed from the output of the action for one state to the
input of the actions for another state.
Swimlanes visually organize responsibility for actions and subactions. They often
correspond to organizational units in a business model.

Rational Rhapsody 621

Activity diagrams

Reference activities references an activity in another activity chart, or to the entire

activity chart itself.

Advanced features of activity diagrams

You might also use these advanced features of the activity diagrams:

Naming and renaming activity diagrams

Include an activity diagram, but not a statechart, with a package without creating a class
Support multiple activities in a package
Associate an object node with a class

Create Adding call behaviors in the activity diagram or by dropping an operation from the
browser into the diagram
Swimlane association (representing field population) to a class (only) can be created by
dragging the class from the browser to the Swimlane name compartment. For more
information, see Swimlanes.
Reference an alternate activity diagram within the main behavior activity diagram

Actions
Activity diagrams are flowcharts that decompose a system into activities that correspond to states.
These diagrammatic elements, called actions, are member function calls within a given operation.
In contrast to normal states (as in statecharts), actions in activity diagrams terminate on completion
of the activity, rather than as a reaction to an externally generated event.

Each action can have an entry action, and must have at least one outgoing activity flow. The
implicit event trigger on the outgoing activity flow is the completion of the entry action. If the
action has several outgoing transitions, each must have its own guard condition.

Actions have the following constraints:

Outgoing transitions from actions do not include an event signature. They can include
guard conditions and actions.
Actions have non-empty entry actions.
Actions do not have internal transitions or exit actions, nor do activities.
Outgoing transitions on actions have no triggering events.

622 User Guide

 Activity diagram elements

Activity diagram elements

The following sections describe how to use the activity diagram drawing tools to draw the parts of
an activity diagram. For basic information on diagrams, including how to create, open, and delete
them, see Graphic editors.

Activity diagram drawing tools

The Diagram Tools toolbar for an activity diagram contains the following tools.

Drawing
Icon Name Description
Tool
Accept Event Adds this element to an activity diagram so that you can connect it to an action to
Action show the resulting action for an event. This element can specify the following
actions:
• Event to send
• Event target
• Values for event arguments
This button displays on Diagram Tools when you select the Analysis Only check
box when you define the General features of the activity diagram.
Accept Time Adds an element that denotes the time elapsed since the current state was entered.
Event
Action Shows member function calls within a given operation.

Action Block Represents compound actions that can be decomposed into actions. Action blocks
can show more detail than is possible in a single, top-level action
Action Pin Adds an element to represent the inputs and outputs for the relevant action or action
block. An action pin can be used on a Call Operation (derived from the arguments).
This button displays in on Diagram Tools when you select the Analysis Only check
box when defining the general features of the activity diagram. For more information,
see Add action pins/activity parameters to diagrams.
Activity Final Signifies either local or global termination, depending on where they are placed in
the diagram.
Activity Flow Add or modify a text describing a transition.
Label
Activity Defines a characteristic of an action block. This button displays on Diagram Tools
Parameter when you select the Analysis Only check box when defining the general features of
the activity diagram. For more information, see Add action pins/activity
parameters to diagrams.
Call Behavior Represents a call to an operation of a classifier. This is only used in modeling and
does not generate code for the call operation.
Call Operation Represents a call to an operation of a classifier.

Rational Rhapsody 623

Activity diagrams

Drawing
Icon Name Description
Tool
ControlFlow Represents a message or event that causes an object to transition from one state to
another.

Decision Node Shows a branching condition. A decision node can have only one incoming transition
and two or more outgoing transitions.
Dependency Indicates a dependent relationship between two items in the diagram.

Diagram Connects one part of an activity diagram to another part on the same diagram. They
Connector represent another way to show looping behavior.
Fork Node Separates a single incoming activity flow into multiple outgoing activity flows.

Initial Flow Points to the state that the object, use case, or operation enters when the activity
starts.

Join Node Merges multiple incoming activity flows into a single outgoing activity flow.

Merge Node Joins multiple activity flows into a single, outgoing activity flow.

Object Node Represents an object passed from the output of the action for one state to the input
of the action for another state.
Send Action Represents sending actions to external entities. The Send Action is a language-
independent element, which is translated into the relevant implementation language
during code generation.
Subactivity Represents a nested activity diagram. Subactivities represent the execution of a
non-atomic sequence of steps of some duration nested within another activity.

Swimlane Organizes activity diagrams into sections of responsibility for actions and
Frame subactions.
Swinlane Divides the swimlane frame using vertical, solid lines to separate each swimlane
Divider (actions and subactions) from adjacent swimlanes.

624 User Guide

 Activity diagram elements

Drawing an action
To draw an action for your activity diagram:

1. Click the Action button on Diagram Tools.

2. Click or click-and-drag in the activity diagram to place the action at the intended location.
An action appears on an activity diagram as a rectangle with curved edges.

3. Type a name for the action.

4. Press Ctrl+Enter or click the Select arrow in the toolbar to terminate editing.

By default, the action expression, which does not need to be unique within the diagram, is
displayed inside the action symbol. For information on modifying the display, see Displaying an
action.

Modify the features of an action

Use the Features window for an action to change its features, including its name and action. An
action has the following features:

Name specifies the name of the action. The description of the action can be entered into
the text area on the Description tab. This description can include a hyperlink. For more
information, see Hyperlinks.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the element, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the folder with

binoculars button.

– To sort the order of the stereotypes, click the up and down arrows button.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Action specifies an action in an activity diagram. This is the text you typed into the
diagram when you created the action.

Rational Rhapsody 625

Activity diagrams

Displaying an action
You can show the name, action, or description of the action in the activity diagram.

To specify which attribute to display:

1. Right-click the action and select Display Options to open the Display Options window.
2. Select the appropriate values.

Activity frames
You might want to create an activity frame in the activity diagram to hold a group of elements and
then assign it activity parameters. The parameters indicate inputs and outputs of data to the frame.
The frame can also be synchronized with a call behavior.

Creating an activity frame manually

To create an activity frame manually:

1. In the Rhapsody project, add a class.

2. Right-click the class and select Add New > Diagrams > Activity.

3. Right-click in the diagram drawing area and select the Show/Hide Activity Frame
option. The activity frame displays in the diagram.
You may use the Features window to define the frame.

Creating an activity frame automatically

To create an activity frame automatically for each new activity diagram:

1. Open your Rhapsody project.

2. Right-click the project or a package in the browser and select Features to open the
Features window.

3. On the Properties tab, navigate to the General::Graphics::ShowActivityFrame

property and check the selection box.

4. Click OK.

5. Right-click a class and select Add New > Diagrams > Activity. The new diagram
contains an activity frame.

626 User Guide

 Activity diagram elements

Synchronizing the pins

To synchronize the call behavior pin with the activity frame pin:

1. Right-click in the activity frame and select Features.

2. Select the General tab and check Analysis Only and click OK.

3. Add some activity parameters to the activity frame and set the name, type, and direction of
the pins.

4. Create another activity diagram and check Analysis Only in the General tab.

5. Drag and drop the first activity frame into the second activity diagram.

This action creates call behavior, that is referencing to the first activity, and small pins with the
same name, type and direction as in the referenced activity.

Updating activity pins

To update the activity pins in synchronized activity diagrams, right-click the call behavior and
select Update/Create Activity Pins.

Rational Rhapsody 627

Activity diagrams

Action blocks
Action blocks represent compound actions that can be decomposed into actions. Action blocks can
show more detail than is possible in a single, top-level action. You can also use pseudocode, text,
or mathematical formulas as alternative notations. Activity flows inside an action block cannot
cross the action block boundary.

Creating an action block

To define the activity, draw an action block:

1. Click the Action Block button on Diagram Tools.

2. Click or click-and-drag in the activity diagram to place the action block at the intended
location. An action block appears on an activity diagram as a rectangle.

3. Draw actions and activity flows inside the action block to express the activity being
modeled.

The Record_and_Send_Messages activity shown in the following sample action block shows
several activities.

628 User Guide

 Activity diagram elements

Modify the features of an action block

Use the Features window for an action box to change its features, including its name and
description. An action block has the following features:

Name specifies the name of the action block. The description of the action block can be
entered into the text area on the Description tab. This description can include a hyperlink.
For more information, see Hyperlinks.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the action block, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the folder with

binoculars button.

– To sort the order of the stereotypes, click the up and down arrows button.
Note: The COM stereotypes are constructive; that is, they affect code generation.

Creating a subactivity from an action block

You can convert an action block to a subactivity. This moves the contents of the block into a
separate subchart, and simplifies the diagram containing the action block.

To create a subactivity from an action block, right-click the action block and select Create Sub
Activity Diagram. Rational Rhapsody creates a new subchart containing the former contents of
the action block.

Consider the action block shown in the following figure. When you create a subactivity for the
action block, the parent state changes to that shown in the following figure.

Rational Rhapsody 629

Activity diagrams

The icon in the lower right corner indicates that the action block has a subchart.

Subactivities
Subactivities represent nested activity diagrams. Subactivities represent the execution of a non-
atomic sequence of steps of some duration nested within another activity. Internally, a subactivity
consists of a set of actions, and possibly a wait for events. In other words, a subactivity is a
hierarchical action during which an associated subactivity diagram is executed. Therefore, a
subactivity is a submachine state that executes an activity diagram.

The nested activity diagram must have an initial (default) state and a final activity (see Local
termination semantics). When an input activity flow to the subactivity is triggered, execution
begins with the initial state of the nested activity diagram. The outgoing activity flows from a
subactivity are enabled when the final activity of the nested activity diagram is reached (when the
activity completes) or when triggering events occur on the transitions. Because states in activity
diagrams normally do not have triggering events, subactivities are normally exited when their
nested graph is finished.

Many subactivities can start a single-nested activity diagram.

Creating a subactivity
To draw a subactivity:

1. Click the Subactivity button on Diagram Tools.

2. Click (or click-and-drag) in the activity diagram to place the subactivity at the intended
location.
A subactivity looks like an action.

Opening a subactivity diagram

To open a subactivity diagram, right-click the subactivity and select Open Sub Activity Diagram.

630 User Guide

 Activity diagram elements

Creating a final activity

UML final state (“activity final” in Rational Rhapsody) can signify either local or global
termination, depending on where they are placed in the diagram. When the state is drawn inside a
composite (block) state, it is considered a final state. This terminates the activity represented by
the composite state, but not the instance performing the activity. For more information, see Local
termination semantics. When the state is drawn inside the top state, it is considered a final activity.
This terminates the state machine causing the instance to be destroyed.

Note
The behavior of “activity final” is controlled by the
CG::Statechart::LocalTerminationSemantics property.

To create a final activity:

1. Click the Activity Final button .

2. Click in the activity diagram to place the final activity at the intended location.
3. Draw a activity flow from any kind of state to the final activity.

4. If wanted, enter a guard condition to signal the end of the activity. A final activity appears
as a circle with a black dot in the middle:

As with the other connectors, final activities and their activity flows are included in the browser
view.

Rational Rhapsody 631

Activity diagrams

Object nodes
Actions operate on objects and are used by objects. These objects either initiate an action or are
used by an action. Normally, actions specify calls sent between the object owning the activity
diagram (which initiates actions) and the objects that are the targets of the actions. An object node
represents an object passed from the output of the action for one state to the input of the action for
another state.

Note
An object node can only be a leaf element; its meaning cannot contain other elements.
As with other states, only one object node can have the same name in the same parent state.

Creating an object node

To create an object node:

1. Click the Object Node button on Diagram Tools.

2. Click or click-and-drag in the activity diagram to place the node at the intended location.

Display options for an object node

After creating an object node, right-click the diagram and select Display Options. Make your
selections from these settings:

Display name - Represents only, Name, or Label.

Show Stereotype Label
View Image - Enable Image View activates Use Associated Image or Select on Image
with Image Path
Advanced view image features - Image Only, Structured, or Compartment

632 User Guide

 Activity diagram elements

Object node features

The Features window enables you to change the features of an object node, including its name and
stereotype.

Name specifies the name of the object node. The default name is state_n, where n is an
incremental integer starting with 0. The description of the action block can be entered into
the text area on the Description tab.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the object node, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the folder with

binoculars button.

– To sort the order of the stereotypes, click the up and down arrows button.
Note: The COM stereotypes are constructive; that is, they affect code generation.
In State specifies the required states of the object node.
Represents lets you select a class/type to associate with the node from a list of project
classes/types or enter the name of a new class. For more information, see Associate an
object node with a class.

Associate an object node with a class

In an activity diagram, you can associate an object node to a class/type to represent the class type
using one of the following methods:

Right-click the object node in the diagram to display the Features window and select the
class/type from the list in the Represents field.
Dragging a class/type from the browser into the activity diagram automatically associates
the class/type with the object node.
In the activity diagram, the associated node displays the name of its associated class/type in the
name compartment.

Rational Rhapsody 633

Activity diagrams

Adding call behaviors

A call behavior represents a call to an operation of a classifier. This is only used in modeling and
does not generate code for the call operation. However, code can be inserted manually into the
Action field in the Call Behavior Features window. To create a call operation node, use one of
these methods:

Click the Call Behavior button on Diagram Tools and drawing the behavior operation
in the diagram.
Click or click-and-drag an operation from the browser in the activity diagram and place
the behavior at the intended location.

Note
If the behavior operation dropped in the activity diagram has no association with the
classifier, an empty call is created.

Activity flows
Activity diagrams can have activity flows, default flows, and loop activity flows on action blocks
and join activity flows. These activity flows in activity diagrams are the same as the corresponding
activity flows in statecharts, with the following exceptions:

Outgoing activity flows from states can have triggers, but those from actions, action
blocks, or subactivities cannot.
Outgoing activity flows from actions, action blocks, and subactivities can have only
guards and actions.
Activity flows exiting or entering fork or join bars have the following constraints:

They cannot have labels.

They must originate in, or target, either states or actions (not connectors).

Creating an activity flow

To draw an activity flow from one state to another:

1. Click the Activity Flow button on Diagram Tools.

2. Click the edge of the source state.

3. Drag the cursor to the edge of the target state and release to anchor the activity flow.

4. If wanted, enter a trigger for the activity flow.

5. If wanted, enter a guard and action for the activity flow.

634 User Guide

 Activity diagram elements

Completion activity flows

An activity flow to a final activity is called a completion activity flow. Neither final states nor a
final activity can have outgoing transitions. A completion activity flow does not have an explicit
trigger, although it can have a guard condition.

Drawing initial flows

The default flow points to the state that the object, use case, or operation enters when the activity
starts.

To draw a default flow:

1. Click the Initial Flow button on Diagram Tools.

2. Click in the activity diagram outside the default state.

3. Drag the cursor to the edge of the default state of the activity and release the mouse button.
For more information on default flows, see Statecharts.

Drawing loop activity flows

Loop activity flows (also known as self transitions) represent looping behavior in a program. Loop
activity flows are often used on action blocks to indicate that the block should loop until some exit
condition becomes true.

To draw a loop activity flow:

1. Click the Loop Activity Flow button on Diagram Tools.

2. Click the edge of any kind of state.

3. Label the loop activity flow.

For an example of an action block with a loop activity flow, see Creating a final activity. For more
information on loop (self) transitions, see Statecharts.

Rational Rhapsody 635

Activity diagrams

Adding or modifying activity flow labels

To add or modify a activity flow label:

1. Click the Activity Flow Label button on Diagram Tools.

2. Select the transition you want to label.

3. In the edit box, type the new label (or modify the existing one).
4. Press Ctrl+Enter or click outside the label to terminate editing.

Modify activity flows

As with all other elements, you can modify the features of a activity flow using the Features
window. For more information, see Features of transitions.

Connectors
Activity diagrams can have the following connectors:

Merge nodes
Condition
Diagram
The following sections describe these connectors in detail.

Drawing merge nodes

To draw a merge node:

1. Click the Merge Node button .

2. Click in the activity diagram to place the junction at the intended location.
3. Draw activity flows going into, and one activity flow going out of the junction.

4. Label the activity flows as wanted.

For more information on merge nodes, see Statecharts.

636 User Guide

 Activity diagram elements

Drawing decision nodes

Decision nodes show branching conditions. A decision node can have only one incoming activity
flow and two or more outgoing activity flows. The outgoing activity flows are labeled with a
distinct guard condition and no event trigger. A predefined guard, denoted [else], can be used
for no more than one outgoing activity flow.

To draw a decision node:

1. Click the Decision Node button .

2. Click, or click-and-drag, in the activity diagram to position the decision node at the
intended location. A decision node appears on an activity diagram as a diamond.

3. Draw at least two states that will become targets of the outgoing activity flows.

4. Draw an incoming activity flow from the source state to the decision node.

5. Draw and label the outgoing activity flows from the decision node to the target states.
This activity diagram shows the following behavior: When the phone rings, if someone picks up
on the other end, you can talk; otherwise, you must leave a message. The decision node represents
the decision point. In other words, after the PhoneRings() operation, if SomeonePicksUp
resolves to True, the Talk() operation is called. Otherwise, the LeaveMessage() operation is
called.

Use the Display Options window to determine whether to display the name, label, or nothing for
the decision node.

Rational Rhapsody 637

Activity diagrams

Drawing diagram connectors

Diagram connectors connect one part of an activity diagram to another part on the same diagram.
They represent another way to show looping behavior.

To draw a diagram connector:

1. Click the Diagram Connector button on Diagram Tools.

2. Click to place the source diagram connector at the intended location and label the
connector.

3. Repeat to place the target diagram connector at the intended location in the diagram, and
give it the same name as the source connector.

For more information on diagram connectors, see Statecharts.

Join or fork bars

Activity diagrams can include join or fork bars. A join or fork bar depicts either a join or a fork
operation. You can draw join or fork bars in activity diagrams for objects, use cases, and
operations.

Rational Rhapsody defines activity diagrams as meaningful only if join and fork bars are well-
structured in the same sense as well-structured parentheses. In other words, they must use proper
nesting. The only exception to this rule is that a join or fork connector with multiple ingoing/
outgoing activity flows can be used in place of a number of join or fork connectors with only two
ingoing or outgoing activity flows each.

Rational Rhapsody tolerates less-than-meaningful activity charts, provided that they can be
extended into meaningful ones by adding activity flows (for example, a fork with activity flows
that never merge back).

As you draw activity diagrams, Rational Rhapsody prevents you from drawing constructs that
violate the meaningfulness of the activity diagram by displaying a “no entry” symbol.

638 User Guide

 Activity diagram elements

Creating join nodes

To draw a join nodes:

1. Draw at least two states that you want to synchronize.

2. Click the Join Node button on Diagram Tools.

3. Click or click-and-drag in the activity diagram to place the join node bar in the intended
location.

By default, the join bar is drawn horizontally. To flip it, see Rotating join or fork bars.
4. Draw incoming activity flows from each of the source states to the join node bar.

5. Draw a state that will be the target of the outgoing activity flow.

6. Draw an outgoing activity flow from the join node bar to the target state.

A join node is shown as a bar with two or more incoming activity flow arrows and one outgoing
activity flow arrow.

Creating fork nodes

To draw a fork nodes:

1. Click the Fork Node button on Diagram Tools.

2. Click, or click-and-drag, in the activity diagram to place the fork node bar at the intended
location. Fork node bars can be vertical or horizontal only.

By default, the join line is drawn horizontally. To flip it, see Rotating join or fork bars.

3. Draw a source state and an incoming activity flow coming into the fork node bar.

4. Draw the target states and the outgoing activity flows from the fork node bar.

Rational Rhapsody 639

Activity diagrams

A fork node is shown as a heavy bar with one incoming activity flow and two or more outgoing
activity flow arrows.

Rotating join or fork bars

You can rotate a join or fork bar to the right (clockwise) or left (counter-clockwise).

To rotate a join or fork bar, right-click the join or fork bar and select either Flip Right or Flip Left.

Stretching join or fork bars

To stretch a join or fork bar:

1. Select the join or fork bar.

2. Click-and-drag one of the highlighted selection handles until the join or fork bar is the
wanted length.

Moving join or fork bars

To move a join or fork bar to a new location:

1. Click in the middle of the join or fork bar, away from the selection handles, and drag the
bar to the intended location.

2. Release the mouse button to place the join or fork bar at the new location.

640 User Guide

 Activity diagram elements

Modify join or fork bars

As with all other elements, you can modify the features of a join or fork bar using the Features
window. The fields and buttons are as follows:

Name specifies the name of the element. The default name is <element>_n, where n is
an incremental integer starting with 0. Add any additional information using the
Description tab.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the element, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the folder with

binoculars button.

– To sort the order of the stereotypes, click the up and down arrows button.
Note: The COM stereotypes are constructive; that is, they affect code generation.

Rational Rhapsody 641

Activity diagrams

Swimlanes
Swimlanes divide activity diagrams into sections. Each swimlane is separated from adjacent
swimlanes by vertical, solid lines on both sides. These are the features of swimlanes:

Each action is assigned to one swimlane.

Activity flows can cross lanes.
Swimlanes do not change ownership hierarchy.
Swimlane association (representing field population) to a class (only) can be created by
dragging the class from the browser to the Swimlane name compartment.
The relative ordering of swimlanes has no semantic significance.
There is no significance to the routing of an activity flow path.
The following figure shows an activity diagram with swimlanes.

642 User Guide

 Activity diagram elements

Creating swimlanes
To use swimlanes in an activity diagram, you first need to create a swimlane frame. If you do not,
Rational Rhapsody generates an error message.

Note
There can be only one swimlane frame in an activity diagram. Once you have created a
frame, the Swimlane Frame tool is unavailable.
To draw a swimlane:

1. Click the Swimlane Frame button on Diagram Tools.

2. The cursor turns into crosshairs. In the drawing area, click one corner to draw the
swimlane frame (a box).

3. Click the Swimlane Divider button on Diagram Tools.

4. The cursor turns into a vertical bar. When it is at the intended location, left-click to place
the divider. Rational Rhapsody creates two swimlanes, named swimlane_n and
swimlane_n+1, where n is an incremental integer starting at 0.

If you draw another divider, it divides the existing swimlane into two swimlanes, with the
new swimlane positioned to the left of the divider.

Note: You cannot draw a swimlane on an existing state.

5. If wanted, rename the swimlanes using the Features window.

Note the following information:

Swimlanes have a minimum width. If you enlarge a swimlane, the extra space is added to
the right of the swimlane. To resize a swimlane, move the divider to the left or the right.
If a swimlane contains activity diagram elements, you cannot reduce the size of that
swimlane so its divider is positioned to the left of any of those elements, because that
would force the elements into a different swimlane.
A swimlane maps into a partition of states in the activity diagram. A state symbol in a
swimlane cases the corresponding state to belong to the corresponding partition.

Rational Rhapsody 643

Activity diagrams

Modify the features of a swimlane

The Features window enables you to change the features of a swimlane, including its name and
description. A swimlane has the following features:

Name specifies the name of the element. The default name is swimlane_n, where n is an
incremental integer starting with 0. Add any additional information using the Description
tab.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the swimlane, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.
– To select from a list of current stereotypes in the project, click the folder with
binoculars button.

– To sort the order of the stereotypes, click the up and down arrows button.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Represents specifies the class to which the swimlane applies.

View swimlanes in the browser

Swimlanes are displayed in the browser under the activity diagram, as shown in the following
figure.

Note
Swimlane nodes cannot be deleted.

Deleting swimlane dividers

To delete a swimlane:

1. Select the divider you want to delete.

2. Click the Delete button on your keyboard.

644 User Guide

 Activity diagram elements

Deleting the swimlane frame

To delete the swimlane frame and all its swimlanes:

1. Select the frame.

2. Click the Delete button on your keyboard.

Note that after the deletion, the frame and swimlanes are removed, but the elements they contained
still exist in the activity diagram.

Swimlane limitations
Note the following design and behavior limitations apply to swimlanes:

You should not draw actions on swimlane divider lines. In other words, do not draw
actions that overlap into another swimlane.
Swimlanes in subactivity diagrams are not supported.
You cannot use the browser to create or drag-and-drop swimlanes.

Rational Rhapsody 645

Activity diagrams

Adding calls to behaviors

You can add a call to a behavior in another activity diagram or to the entire activity diagram. You
can add calls to both activity diagrams and subactivity diagrams.

To add a call, either click the Call Behavior button on Diagram Tools, or drag-and-drop the
activity (or activity diagram) from the browser into the activity diagram. Rational Rhapsody
creates the call in the activity diagram and in the browser.

The called behavior has the same name as the called object. The called behavior, PushButton, is
marked with an at-symbol icon, as shown in the following figure.

This is displayed in the project browser under the activity diagram containing the behavior.

646 User Guide

 Activity diagram elements

Modifying a called behavior

To modify the features of a called behavior:

1. Highlight the called behavior in either the browser or diagram. Right-click and select
Features.

2. Click the right arrow button beside the Reference field in the General tab.

3. Use the ActivityGraph Tree window to navigate to the activity diagram that the called
behavior represents.

Display called behaviors

As with most elements, use the Display Options window to define the display of called behaviors
with one of these options:

Show the name, label, or nothing for the activity

Show the name, label, or icon for the stereotype

Called behavior limitations

Note the following behavior and restrictions:

You cannot “undo” changes to called behaviors.

A called behavior cannot be created in the browser.
There is no code generation for called behaviors because the code generator ignores these
calls and the activity flows that go in and out of them.

Rational Rhapsody 647

Activity diagrams

Add action pins/activity parameters to diagrams

Action pins can be added to actions and activity parameters can be added to action blocks in an
activity diagram. These elements represent the inputs and outputs for the relevant action/action
block. Action pins can also be added to subactivities.

Action pins and activity parameters are diagram elements and appear in the browser. However,
there is no code generated for these elements.

Making the action pin tool available

To make the action pin tool available for use:

1. Highlight an element in the browser that needs an activity diagram for analysis purposes
only.

2. Right-click the element and select Add New > Diagrams > Activity Diagram.

3. Right-click the Activity Diagram now listed in the browser and select Features to open
the Features window.

4. Select the Analysis Only check box on the General tab.

5. Click OK. Rational Rhapsody displays a message asking if you intend to create an
analysis only activity diagram. If you click Yes, this diagram cannot be used for other
purposes than analysis.

6. The system then places the Action Pin and Activity Parameter buttons on Diagram
Tools.

648 User Guide

 Activity diagram elements

Using the action pin

To use the action pin:

1. Click the small Action Pin button at the bottom of the available Diagram Tools.

2. Click the action to which the pin should be added.

The pin displays on the border of the action closest to the point that was clicked. The name
displays alongside the pin. The default name is pin_n.

Adding an activity parameter

To add an activity parameter:

1. Click the Activity Parameter button at the bottom of the Diagram Tools.

2. Click the action block to which the activity parameter should be added.

The activity parameter displays on the border of the action block closest to the point that was
clicked. The name displays inside the activity parameter node. The default name is parameter_n.

Modify features of action pins / activity parameters

The Features window enables you to change the following features of action pins / activity
parameters, in addition to the standard fields:

Direction (in, out, inOut)

Argument Type (for example, int)

Graphical characteristics of action pins / activity parameters

Action pins and activity parameter nodes have the following graphical characteristics:

Pins/parameters always remain attached to their action/action block. However, they can be
moved around the perimeter of the action/action block.
Action pins are a fixed size. Activity parameters, however, can be resized.
Pins/parameters cannot be copied and pasted.
All pin/parameter operations can be undone.
In the browser, pins/parameters appear beneath the action/action block to which they
belong.
When an action pin / activity parameter is deleted from a diagram, it is removed from both
the view and the model.

Rational Rhapsody 649

Activity diagrams

Other characteristics of action pins / activity parameters

Appear in reports generated by the internal Rational Rhapsody reporter.
Appear in reports generated by ReporterPLUS.
Are exported to DOORS.
Are exported to XMI files using the XMI toolkit.
Supported in DiffMerge.
Appear in the Search window.
Supported in the Rational Rhapsody API. It returns the pins/parameters associated with an
action, as well as the type of each pin/parameter.

Local termination semantics

Local termination means that once an action block is entered, it can be exited by a null transition
only if its final state has been reached. A null transition is any transition without a trigger (event or
timeout). A null transition can have a guard.

Statechart mode
The following sections describe how local termination is implemented in statechart mode for
various kinds of states.

Or states
The following local termination rules apply to Or states:

An Or state that has a final activity is completed when the final activity is reached.
An Or state without a final activity is completed after finishing its entry action.
An outgoing activity flow from an Or state can have a trigger (as with statecharts).
An outgoing null transition (activity flow without a trigger) from an Or state can be taken
only if the Or state is completed.
If an Or state with a final activity has a history connector, the last state of the history
connector is always the final activity, after it has been reached once.
An Or state can be exited by any activity flow, including a null transition, from one of its
substates (as with statecharts).

Leaf states
A leaf state is completed after finishing its entry action.

650 User Guide

 Activity diagram elements

Component states
The following local termination rules apply to component states:

Because a component state is a kind of Or state, all the local termination rules for Or states
also apply to component states.
A join transition (from several component states) is activated only if all the sources
(component states) are completed.

And states
An outgoing null transition from an And state is activated only if all of its components are
completed.

IS_COMPLETED() macro
You can use the IS_COMPLETED() macro in a statechart to test whether a state is completed.
Completion means that any of the conditions for local termination described in the previous
sections are true. The macro works the same for both flat and reusable implementations of
statecharts.

The CG::Class::IsCompletedForAllStates property specifies whether the IS_COMPLETED()

macro can be used for all kinds of states. The default value of Cleared means that the macro can
be used only for states that have a final activity. Checked means that it can be used for all states.

Activity diagram mode

All of the local termination rules for statechart mode also apply in activity diagram mode, with the
following exceptions:

An Or state that has a final activity is completed when the final activity is reached.
An Or state without a final activity is never completed.

Rational Rhapsody 651

Activity diagrams

Code generation
In previous releases, Rational Rhapsody supported code generation only from activity diagrams
associated with classes, not from activity diagrams associated with operations or use cases.

Rational Rhapsody Developer for C++ generates functor-based code for activity diagrams
associated with operations. Functor-based code reuses the code generation functionality for
activity diagrams of classes. Code is generated into a new class (called the functor class), which
implements an activity diagram on the class level. The task of executing the modeled operation (an
operation associated with an activity diagram) is delegated to the new class. The class that
delegates the task is known as the owner class.

You specify whether to generate code for an activity diagram by setting the property
CPP_CG::Operation::ImplementActivityDiagram to Checked. This property is set to Cleared
by default.

Functor classes
Consider the following class:

The following figure shows the activity diagram associated with the increaseSpeed modeled
operation.

652 User Guide

 Code generation

In the example model, Motor is the owner class, and FunctorIncreaseSpeed_int executes
the modeled operation increaseSpeed.

This activity diagram increments the value of the class attribute speed by the value specified by
the amount argument, then returns the incremental value. Note the following information:

An activity diagram should never contain code with the return keyword because the
current implementation executes the code fragments of the diagram (that appear in
actions, activity flows, and so on) in contexts of different operations. Returning from
those contexts (operations) does not have the same effect as returning from the body of a
regular operation.

Instead, you should set the return value to the rpyRetVal variable (shown in the
previous figure), which is always generated for operations that return values.
There are two ways an operation can finish and return control to its caller:
– Once the diagram reaches a “stable” state (there are no more activity flows to
take), the operation is considered to have finished its job and it returns control
to its caller.
– The diagram reaches a termination connector at the top level.
The actual execution of the code does not occur within the scope of the object that owns
the operation. Instead, the code is executed in another object whose sole purpose is to
execute the diagram. During the execution of the code in the diagram, the this pointer
references a special-purpose object (the functor object) that contains the code in the
diagram (in states, on activity flows, and so on). To refer to the owner object, you can use
the this_ variable, which always exists for this purpose.

To make coding more natural, direct access to the attributes of the class that owns the
operation (without the need for this_) is made possible by supplying references in the
functor object. The functor class contains references that correspond to each owner class
attribute and have the same name. The constructor of the functor class contains arguments
to initialize each attribute; initialization is done when the owner class creates an object of
the functor class.

You can control the code generation of the attribute references by setting the value of the
CPP_CG::Operation::ActivityReferenceToAttributes property to Checked (the
default value).

Rational Rhapsody 653

Activity diagrams

Limitations and specified behavior

Note the following restrictions and behavior:

Activity diagrams do not require “And” states to represent concurrent behavior. Activity
diagrams cannot include “And” states.
Forks can end in states that are not within two orthogonal states.
Activity diagrams for operations cannot receive events, nor can they have state nodes.
You cannot animate the activity diagrams associated with operations. However, an
animated sequence diagram for the model records the fact that a modeled operation was
called. In addition, the call and object stacks record the owner object (not the functor
object) as the object that receives the message.
This feature supports only a subclass of diagrams that do not contain events (including
timeout events) or triggered operations.
If a class attribute and an argument of the modeled operation have the same name, there
will be a name collision that results in a compiler error. To avoid this problem before
attempting to generate code, omit the class attribute that causes the collision. This should
not affect the semantics of the operation, because operation arguments hide class
attributes.
The name of the functor class will contain the signature of the modeled operation, thereby
supporting overloaded operations. Complicated type names will be converted to strings
appropriate for building C++ identifiers. For example, “::” characters are replaced with
underscores.
Because the code in the diagram does not execute within the scope of the modeled
operation, there is no direct access to the this variable. Instead, access this variable
using the this_ attribute of the functor class. This is also the preferred way to start
methods in the owner class.
Operations with variable-length argument lists are not supported.
Global operations with activity diagrams are not supported.

654 User Guide

 Flow charts

A flow chart is a schematic representation of an algorithm or a process. In UML and Rational

Rhapsody, you can think of a flow chart as a subset of an activity diagram that is defined on
methods and functions.

You can model methods and functions using flow charts in all Rational Rhapsody programming
languages. Only in Rational Rhapsody in C and Rational Rhapsody in C++ can readable structured
code be generated from a flow chart. During code generation, for the actions defined in a flow
chart Rational Rhapsody can generate structured code for If/Then/Else, Do/While, and While/
Loops.

The code generator algorithm for a flow chart can identify Loops and Ifs, the expressions for these
constructs is on the guards of the action flows.

For more information about activity diagrams, see Activity diagrams.

Define algorithms with flow charts

One useful application of flow charts is in the definition of algorithms. Algorithms are essentially
decompositions of functions into smaller functions that specify the activities encompassed within a
given process.

This flow chart approach to code generation is to reduce the diagram to blocks of sequential code
and then search for If/Loop patterns in those blocks. The following structured programming
control structures are supported in flow charts:

Simple If
If/Then/Else
While loops (where the test is at the start of the loop)
Do/While loops (where the test is at the end of the loop)
If the algorithm does not succeed to impose the above structure, then it will need to use a GoTo.

Rational Rhapsody 655

Flow charts

Flow charts similarity to activity diagrams

Flow charts have the following elements in common with activity diagrams including start and end
activities and actions:

Decision points that show branching points in the program flow based on guard
conditions.
Actions that represent function invocations with a single exit action flow taken when the
function completes. It is not necessary for all actions to be within the same object.
Action blocks that represent compound actions that can be decomposed into actions.
However, flow charts do not include And states, and flow charts for operations cannot receive
events.

Rational Rhapsody in C includes a Flowchart model located in the <Rational Rhapsody

installation>\Samples\CSamples\Flowchart folder. These sample flow charts show which
flow chart patterns are recognized in order to generate structured code. The following illustration
shows the main elements of a flow chart:

Start Action
(Initial Flow)

Action

Guard Guard

Decision Point End Action

(Merge Node) (Activity Final)

656 User Guide

 Create flow chart elements

Create flow chart elements

You use the flow chart drawing tools to draw the parts of a flow chart. For basic information on
diagrams, including how to create, open, and delete them, see Graphic editors.

Tools for drawing flow charts

The Diagram Tools for a flow chart contains the following tools.

Drawing
Button Name Description
Buttons
Action Represents the member function call within a given operation. For more
information, see Actions.
Action Block Represents compound actions that can be decomposed into actions. For more
information, see Action blocks.
Activity Flow Defines the flow and its guards to supply the test for Ifs or Loops. Activity flows
without guards define the default sequential flow of the flow chart. For more
information, see Activity flows.
Initial Flow Shows the flow origination point from an element. For flow charts, this default
flow is the initial flow, and for code purposes, indicates the start of code. For
more information, see Drawing initial flows.
Loop Activity Represents behavior repeating in a program. For more information, see
Flow Drawing loop activity flows.

DecisionNode Shows branching conditions. For more information, see Drawing decision
nodes.

ActivityFinal Provides local termination semantics. The flow chart returns at this point to the
operation/function that started it. For more information, see Activity final.
MergeNode Combines different flows to a common target. For more information, see
Drawing merge nodes.
Send Action Represents the sending of events to external entities. For more information, see
Send action elements.

Rational Rhapsody 657

Flow charts

Actions
Flow charts decompose a system into actions that correspond to activities. These diagrammatic
elements, called actions, are member function calls within a given operation. In contrast to normal
states (as in statecharts), actions in flow charts terminate on completion of the activity, rather than
as a reaction to an externally generated event.

Each action can have an entry action, and must have at least one outgoing action flow. The implicit
event trigger on the outgoing action flow is the completion of the entry action. If the action has
several outgoing action flows, each must have its own guard condition.

During code generation, code is derived from the actions on a flow chart.

Actions have the following constraints:

Outgoing activity flows can include only guard conditions.

Actions have non-empty entry actions.
Actions do not have internal action flows or exit actions, nor do activities.
Outgoing action flows on actions have no triggering events.

Creating a flow chart

You can create a flow chart on any function or class method in the same way as you can an activity
diagram.

To create a flow chart:

1. In the browser, right-click the model element for which you want to create a flow chart,
such as a function.

2. Select Add New > Diagrams > Flowchart.

The flow chart displays in the Drawing area.

658 User Guide

 Create flow chart elements

Drawing an action
To draw an action:

1. Create a flow chart and click the Action button on Diagram Tools.

2. Click or click-and-drag in the flow chart to place the action where you want it.
An action appears on a flow chart as a rectangle with curved edges.

3. Type a name for the action, then press Ctrl+Enter or click the Select arrow in the toolbar
to terminate typing mode.

By default, the action expression, which does not need to be unique within the flow chart, is
displayed inside the action symbol. For information on modifying the display, see Displaying an
action.

Modify the features of an action

The Features window enables you to add and change the features of an action, including its name
and action. An action has the following features:

Name specifies the name of the action. The description of the action can be entered into
the text area on the Description tab. This description can include a hyperlink. For more
information, see Hyperlinks.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the element, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes. By default, flow charts have a new
term stereotype of “flowchart.”
Note: The COM stereotypes are constructive; that is, they affect code generation.
Action specifies an action in a flow chart. This is the text you typed into the flow chart
when you created the action.

The Overridden check box allows you to toggle the check box on and off to view the
inherited information in each of the window fields and decide whether to apply the
information or revert back to the currently overridden information.
For more information about the Features window, see The Features window.

Rational Rhapsody 659

Flow charts

Displaying an action
You can show the name, action, or description of the action in the flow chart.

To specify which attribute to display:

1. Right-click the action and select Display Options to open the Display Options window.
2. Select the appropriate values and click OK.

Action blocks
Action blocks represent compound actions that can be decomposed into actions. Action blocks can
show more detail than might be possible in a single, top-level action. You can also use pseudocode,
text, or mathematical formulas as alternative notations.

Note that for action blocks, there must be a default flow at the start and a final activity at the end,
and activity flows cannot cross the blocks boundaries to actions in the block (though they might
enter and leave the block itself). The code generator will put blocks code in curly braces and this
has language significance regarding variable scope and lifetime.

Creating an action block

To define the activity, draw an action block:

1. Click the Action Block button on Diagram Tools.

2. Click or click-and-drag in the flow chart to place the action block where you want it.
Action blocks appear as rectangles on a flow chart.

3. Draw actions and activity flows inside the action block to express the activity being
modeled.

660 User Guide

 Create flow chart elements

The Record_and_Send_Messages activity shown in the following sample action block

encompasses several activities.

Modify the features of an action block

The Features window enables you to change the features of an action block, including its name and
description. An action block has the following features:

Name specifies the name of the action block. The description of the action block can be
entered into the text area on the Description tab. This description can include a hyperlink.
For more information, see Hyperlinks.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the action block, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes. By default, flow charts have a
new term stereotype of “flowchart.”
Note: The COM stereotypes are constructive; that is, they affect code generation.

Rational Rhapsody 661

Flow charts

Activity final
An activity final provides local termination semantics. The flow chart returns at this point to
the operation/function that started it.

Note
The behavior of the “activity final” is controlled by the
CG::Statechart::LocalTerminationSemantics property. See the definition provided for
the property on the applicable Properties tab of the Features window.

Creating an activity final

To create a final activity:

1. Click the ActivityFinal button on Diagram Tools.

2. Click in the flow chart to place the final activity where you want it.
A final activity looks like a circle with a black dot in its center.

3. Draw an activity flow from an action to the final activity.

4. If you want, enter a guard condition to signal the end of the activity.
As with the other connectors, final activities and their flows are included in the Rational Rhapsody
browser.

662 User Guide

 Create flow chart elements

Activity flows
Flow charts can have activity flows (such as activity flows, default flows, and loop activity flows)
on actions and action blocks. Activity flows define flow and their guards supply the test for Ifs or
Loops. Activity flows without guards define the default sequential flow of the flow chart.

In addition, note the following information:

When an “If” flow is detected, then the activity flow with a guard defined on it is the body
of the “if.”
For all multiple exit activity flows there should always be one without a guard to define
the sequential flow.
Activity flows in flow charts are the same as the corresponding transitions in activity diagrams,
with the following exceptions:

Outgoing activity flows and action blocks cannot have triggers.

Outgoing activity flows from actions and action blocks can only have guards.

Drawing activity flows

To draw an activity from one action to another:

1. Click the Activity Flow button on Diagram Tools.

2. Click the edge of the source action.

3. Drag the cursor to the edge of the target action and release to anchor the activity flow.

4. If you want, enter a guard for the activity flow.

Completion action flows

An action flow to a final activity is called a completion action flow. Final activities cannot have
outgoing action flows. A completion action flow can only have a guard condition.

Rational Rhapsody 663

Flow charts

Drawing initial flows

One of the action elements must be the default action flow. The flow chart flow originates from the
element pointed to by the default flow. For flow charts, this default flow is the initial flow, and for
code purposes, indicates the start of code.

To draw a default flow:

1. Click the Initial Flow button on Diagram Tools.

2. Click in the flow chart outside the default action.

3. Drag the cursor to the edge of the default action of the activity and release the mouse
button.

Drawing loop activity flows

Loop activity flows represent looping behavior in a program. Loop activity flows are often used on
action blocks to indicate that the block should loop until some exit condition becomes true. A loop
activity flow with a guard is in effect a Do-While statement.

To draw a loop activity flow:

1. Click the Loop Activity Flow button on Diagram Tools.

2. Click the edge of an action.

3. Label the loop activity flow and press Ctrl+Enter.

For an example of an action block with a loop activity flow, see Activity final.

Modify action flows

As with all other elements, you can modify the features of an action flow using the Features
window. For more information, see Features of transitions.

Connectors
Flow charts can have the following connectors:

MergeNode
DecisionNode

664 User Guide

 Create flow chart elements

Drawing merge nodes

A merge node combines different flows to a common target.

To draw a merge node:

1. Click the MergeNode button on Diagram Tools.

2. Click in the flow chart to place the junction where you want it.

3. Draw flows going into, and one flow going out of the junction.

4. Label the flows if you want.

For more information on merge nodes, see Statecharts.

Drawing decision nodes

Decision Nodes show branching conditions. A decision node can have only one incoming activity
and two or more outgoing activity flows. The outgoing action flows are labeled with a distinct
guard condition. A predefined guard, denoted [else], can be used for no more than one outgoing
flow.

A decision node appears as a diamond shape on a flow chart.

To draw a decision node:

1. Click the DecisionNode button on Diagram Tools.

2. Click, or click-and-drag, in the flow chart to position the decision node where you want it.

3. Draw at least two actions that will become targets of the outgoing action flows.

4. Draw an incoming action flow from the source action to the decision node.

5. Draw and label the outgoing action flows from the decision node to the target actions.

This flow chart shows the following behavior: When the phone rings, if someone picks up on the
other end, you can talk; otherwise, you must leave a message. The decision node represents the
decision point. In other words, after the PhoneRings() operation, if SomeonePicksUp resolves
to True, the Talk() operation is called. Otherwise, the LeaveMessage() operation is called.

Use the Display Options window for the decision node to determine whether to display its name,
label, or nothing.

Rational Rhapsody 665

Flow charts

Code generation
You specify whether to generate code for a flow chart by setting the
C_CG::Operation::ImplementFlowchart property to Checked (which is the default).

Flow chart limitations and specified behavior

Note the following restrictions and behavior:

You cannot animate or reverse engineer flow charts.

Code generation from flow charts is not supported in Rational Rhapsody in Java and
Rational Rhapsody in Ada.
Flow chart code generation will never write the same action twice.
This feature supports only a subclass of diagrams that do not contain events (including
timeout events) or triggered operations.
Rational Rhapsody makes the following checks:
– If a function already has a body.
– On guards that will be ignored because they are not part of an If/Then/Else or
Loop.
– That the flow chart and all its blocks have one and only one reachable final
activity. If there are no reachable states or more than one, a message will
display.
– That there are no elements with more than one flow between them in the same
direction. If there are more than one, a message will display.
– That all the elements in the flow chart are supported. If unsupported elements
are found, a message will display.
If code generated will contain GoTos, Rational Rhapsody will display a warning message
with an indication as to which flows are causing the warning. Note the following
information:
– Flow charts will normally generate structured code using If, If/Then/Else, Do,
and While blocks. Rational Rhapsody in C provides you with a Flowchart
model located in the <Rational Rhapsody
installation>\Samples\CSamples\
Flowchart folder. The Flowchart model contains a number of sample flow
charts patterns that show you which ones are recognized in order to generate
structured code. For example, the Flowchart model includes flow charts that
show the DoWhileLoop, IfThenElse, and the WhileLoop.

666 User Guide

 Code generation

– If the code is not structured, then the flow charts will generate GoTo code. To
avoid GoTo code, use the sample patterns for structured blocks as shown in
the flow charts that are illustrated and documented in the Flowchart model
provided with Rational Rhapsody in C, which is located in the path noted
above.

Rational Rhapsody 667

Flow charts

668 User Guide

 Sequence diagrams

Sequence diagrams (SDs) describe message exchanges within your project. You can place
messages in a sequence diagram as part of developing the software system. You can also run an
animated sequence diagram to watch messages as they occur in an executing program.

Sequence diagram show scenarios of messages exchanges between roles played by objects. This
functionality can be used in numerous ways, including analysis and design scenarios, execution
traces, expected behavior in test cases, and so on.

Sequence diagrams help you understand the interactions and relationships between objects by
displaying the messages that they send to each other over time. In addition, they are the key tool
for viewing animated execution. When you run an animated program, its system dynamics are
shown as interactions between objects and the relative timing of events.

Sequence diagrams are the most common type of interaction diagrams.

Note
Rational Rhapsody message diagrams are based on sequence diagrams. Message diagrams,
available in the FunctionalC profile, show how the files functionality might interact through
messaging (through synchronous function calls or asynchronous communication). Message
diagrams can be used at different levels of abstraction. At higher levels of abstractions,
message diagrams show the interactions between actors, use cases, and objects. At lower
levels of abstraction and for implementation, message diagrams show the communication
between classes and objects.
Message diagrams have an executable aspect and are a key animation tool. When you
animate a model, Rational Rhapsody dynamically builds message diagrams that record the
object-to-object messaging.

For more information about the FunctionalC profile, see Profiles.

Rational Rhapsody 669

Sequence diagrams

Sequence diagram layout

A sequence diagram has two sections:

Names pane, which is the top portion of the diagram. The Names pane is a control to
identify instance lines when the role names are not visible.
Message pane shows the messages passed between instance lines in the diagram.

670 User Guide

 Sequence diagram layout

Names pane
The names pane contains the name of each instance line or classifier role. In a sequence diagram, a
classifier role represents an instance of a classifier. It describes a specific role played by the
classifier instance to perform a particular task. A classifier role is shown as an instance line with a
text header (name) with a box drawn around it. A classifier role can realize a classifier (class or
actor) of the static model object.

Changing names
Names that are too long to fit in the pane continue past the divider, running down behind the lower
pane. To change the size of the names pane, click the dividing line and drag it up or down.

You can change the font and edit the names in the names pane using the menu for text items.

There are three ways to describe the name:

Classifier Role Name: Classifier Name
: Classifier Name
Classifier Role Name
In the first two cases, if the classifier name does not exist in the metamodel, Rational Rhapsody
asks if you want to add a new classifier to the project. The third case tells Rational Rhapsody that
you want to use an <Unspecified> classifier role, which means that the classifier role is not a
realization of an existing classifier or actor.

Renaming classifier roles

If you change the name of a classifier role to a role name that already exists in the model, the
classifier role is automatically realized to that classifier. For example, if you change the role name
of classifier B to “Alarm” and there is a class Alarm in the model, this role becomes a realization of
class Alarm and its name changes to B::Alarm.

If you change the name to a class that does not yet exist in the model, Rational Rhapsody asks if
you want to create that class. For example, if you type x:X, Rational Rhapsody asks if you want to
create the class X.

Rational Rhapsody 671

Sequence diagrams

Message pane
The message pane contains the elements that make up the interaction. In the object pane, system
borders and instances are displayed as instance line, which are vertical lines with a box containing
the role name at the top. Messages, such as events, operations, and timeouts are generally shown as
horizontal and slanted arrows.

The messages appear in sequence as time advances down the diagram. The vertical distance
between points in time indicates only the sequence in time and not any time scale.

Analysis versus design mode

Three properties (under SequenceDiagram::General) to support the SD operation modes:

ClassCentricMode specifies whether classes are realized when you draw instance lines.
The possible values are as follows:
– Checked means instance names of the form <xxx> are treated as class names,
not instance names. For example, if you create a new instance line named c,
Rational Rhapsody creates a class named c and displays it in the sequence
diagram as :c.
– Cleared means when you create an instance line, it is named role_n by
default, which represents an anonymous instance. This is the default value.
RealizeMessages specifies whether messages are realized when you create them. The
possible values are as follows:
– Checked where in Design mode, when you type in a message name, Rational
Rhapsody asks if you want to realize the message. If you answer no, the
message is unspecified. For example, you could use an unrealized message to
describe a message that is part of the framework (such as takeEvent()),
without actually adding it to the model. (In analysis mode, the confirmation is
controlled by the property
SequenceDiagram::General::ConfirmCreation.)
– Cleared where you can draw message lines freely, without messages from
Rational Rhapsody about realization. This is the default value.
CleanupRealized specifies whether to delete messages in the sequence diagram if the
corresponding operation is deleted. The possible values are as follows:
– Checked means to delete the messages when the operation is deleted.
– Cleared means to not delete the messages when the operation is deleted. This
is the default value.
For sequence diagrams produced in Rational Rhapsody 4.0 or earlier, all three of these properties
are Cleared.

672 User Guide

 Analysis versus design mode

Showing unrealized messages

To show a message that has not been realized, select Edit > Select > Select Un-Realized. The
unrealized message is selected in the sequence diagram.

Realizing a selected element

To realize a selected element:

1. Select the element in the sequence diagram.

2. Select Edit > Auto Realize.

When you realize a message, Rational Rhapsody creates a new message in just the manner as if
you selected <New> in the Realization field in the Features window. If you realize a classifier role,
Rational Rhapsody creates a class with the same name as designated in the role name, with a
leading colon. For example, Dishwasher becomes :Dishwasher.

Rational Rhapsody 673

Sequence diagrams

Creating sequence diagram elements

The following sections describe how to use the sequence diagram tools to draw the parts of a
sequence diagram. For basic information on sequence diagrams, including how to create, open,
and delete them, see Graphic editors.

Sequence diagram drawing tools

The Diagram Tools for a sequence diagram includes the following tools.

Drawing
Name Description
Tool

Instance line Shows how an actors participates in the scenario. For more information, see
Creating an instance line.

System border Represents the environment. Events or operations that do not come from instance
lines shown in the chart are drawn coming from the system border. For more
information, see Creating a system border.
Message Represents an interaction between parts, or between a part and the environment. A
message can be an event, a triggered operation, or a primitive operation. For more
information, see Creating a message.

Reply message Represents the response from a message sent to a part or the environment. For
more information, see Creating a reply message.

Create arrow Marks when an instance is created. It can originate from the system border or
another instance. It is a horizontal, dotted line from the creator object to the new
object. An object can have only one “create arrow.” You can label the create arrow
with construction parameters.

Destroy arrow Marks the destruction of an object. It is a dotted line from the destroying object to the
object being destroyed. It can be either a horizontal line or a message-to-self. For
more information, see Creating a destroy arrow.
Timeout Indicates when an event stops and might include a parameter indicating the length of
the time the event is stopped. This is a type of message that is always
communicating with itself. For more information, see Creating a timeout.

Cancelled indicates the condition when an event that has timed out should restart. For more
timeout information, see Creating a cancelled timeout.

Time interval Can be used to create a waiting state with an event stopping for this predefined
interval and then automatically restarting. For more information, see Specifying a
time interval.
DataFlow Indicates the flow of data between two objects. You can use the Features window to
select the flowport to which it is connected on the receiving object and change the
value being sent. This connection is also automatically added to the sequence
diagram during animation. For more information, see Creating a dataflow.

Partition line Separates phases of a scenario represented in the sequence diagram. For more
information, see Creating a partition line.

674 User Guide

 Creating sequence diagram elements

Drawing
Name Description
Tool
Condition mark Indicates that the object is in a certain condition or state at this point in the sequence.
For more information, see Creating a condition mark.
Execution Shows the beginning and end of the unit of behavior (the actions performed by an
Occurrence operation or event) that is triggered by a specific message. For more information,
see Creating execution occurrences.
Interaction Refers to another sequence from within a sequence diagram. This allows complex
Occurrence scenarios to be divided into smaller, reusable scenarios. For more information, see
Creating an interaction occurrence.
Interaction Groups related elements and define specific conditions under which each group of
Operator elements occurs. For more information, see Creating interaction operators.
Interaction Create two subgroups of elements within the sequence diagram. This might be used
Operand to create two paths that are supposed to be carried out in parallel or to define two
Separator possible paths and a condition that determines which is to be followed. For more
information, see Adding an interaction operand separator to an interaction
operator.
Lost Message Indicates a message sent from an instance that never arrives to its destination. This
item is not supported in code generation or animation.

Found Indicates a message that arrives at an instance, but its target is unknown. This item
Message is not supported in code generation or animation.

Destruction Indicates the destruction of the instance, such as the destroy arrow, has happened.
Event This item is not supported in code generation or animation.

Rational Rhapsody 675

Sequence diagrams

Creating a system border

A system border represents the environment. Events or operations that do not come from instance
lines shown in the chart are drawn coming from the system border.
A system border is a column of diagonal lines, labeled ENV. You can place a system border anywhere an instance line can be placed, but the typical locations are the far left and right edges of the chart.

To create a system border:

1. Click the System border button .

2. Move the cursor into the drawing area, then click to place the system border. At this point,
the system border is anchored in place.

3. Because the system border represents the environment, it is named ENV by default. If
wanted, rename the system border.

676 User Guide

 Creating sequence diagram elements

Creating an instance line

An instance line (or classifier role) is a vertical timeline labeled with the name of an instance. It
represents a typical instance or class in the scenario being described. It can receive messages from
or send messages to other instance lines.

In addition to creating, deleting, and modifying the name of an instance line, you can realize the
instance line to a class or actor in the static model.

1. Click the Instance line button .

2. Move the cursor over the diagram.

3. Move the line to a suitable location, then click to dock the line into place.

4. Type the name of a class or an instance to replace the default name.

5. If you specified design mode, Rational Rhapsody names the instance line :class_n by
default. If the specified class does not exist, Rational Rhapsody asks if you want to create
it. Click OK.

6. You can continue creating instance lines, or return to select mode by clicking the Select
tool.

If you prefer, you can place several lines and rename them later. Rational Rhapsody gives them
default names until you rename them. For information on renaming instance lines, see Message
line menu. Note that the sequence diagram automatically expands the diagram as necessary as you
add more instance lines.

Note
To shift one or more messages to different instance lines, select the relevant messages and
press Ctrl+Right arrow, or Ctrl+Left arrow. The messages “jump” to the new source and
destination instance lines. This replaces the cut and paste (or drag) functionality of
messages between instance lines in the same diagram.

Rational Rhapsody 677

Sequence diagrams

Modifying the features of a classifier role

The Features window enables you to change the features of a classifier role, including its
realization. A classifier role has the following features:

Name specifies the name of the classifier role.

L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the element, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Realization specifies the class being realized by the instance line.
Decomposed specifies the referenced sequence diagram for the instance line, if you are
using part decomposition. For more information, see Part decomposition.
Description describes the classifier role. This field can include a hyperlink. For more
information, see Hyperlinks.

Names of classifier roles

A classifier role (instance line) with a class name is a view of the class in the model. An instance
line with an instance name (of the form instance:class) is also a view of the class in the model.

Instance lines reference classes in the model. If you rename an instance line to another class name
that exists in the model, the line acts as a view to the other class in the model. If the class does not
exist, Rational Rhapsody will create it.

Note
The names for instance lines are resizable text frames. Text wraps to match the contour of
the bounding box.

678 User Guide

 Creating sequence diagram elements

If you specified analysis mode, Rational Rhapsody names the instance line role_n by default and
does not prompt you for class information. The following figure shows a new instance line in an
analysis SD.

If you specified design mode, Rational Rhapsody names the instance line :class_n by default. If
the specified class does not exist, Rational Rhapsody asks if you want to create it. The following
figure shows a new instance line in a design SD.

Note that Classifier role names are animated when their expression can be mapped to an existing
object.

Examples:

We have a class A and an object a:A who is the only object of A. All the following names will be
mapped to it:

:A
a:A
A[0]:A
A[#0]:A
Suppose that instead of a:A, we have a single instance of A as a part itsA of another object b:B.

Rational Rhapsody 679

Sequence diagrams

The instance line can be named as:

:A
b->itsA:A
B[0]->itsA:A
A[#0]:A
B[#0]->itsA->a:A
The same instance mappings apply as described in Instance Names.

Instance line menu

Class displays a submenu of commands for classes.
Open Reference Sequence Diagram opens the reference sequence diagram associated
with the classifier role. This option is unavailable if a reference sequence diagram does
not exist for this classifier role. For more information, see Creating an interaction
occurrence.
Display Options specifies how the element should be displayed.

680 User Guide

 Creating sequence diagram elements

Creating a message
A message represents an interaction between objects, or between an object and the environment. A
message can be an event, a triggered operation, or a primitive operation. In the metamodel, a
message defines a specific kind of communication. The communication could be raising a signal,
invoking an operation, or creating or destroying an instance.

The recipient of a message is either a class or a reactive class. Reactive classes have statecharts,
whereas nonreactive classes do not. Reactive classes can receive events, triggered operations, and
primitive operations. Non-reactive classes can receive only messages that are calls to primitive
operations. Events are usually shown with slanted arrows to imply that they are asynchronous
(delivery takes time). Triggered operations are shown with straight arrows to imply that they are
synchronous (happen immediately).

To create a message:

1. Click the Message (event) button .

2. Move the cursor over the instance lines.

Note: A plus sign displays on each instance line as you move the cursor from one to
the next. This symbol indicates a potential origination point for the wanted
message.
3. Left-click to anchor the start of the message at the intended location, then move the cursor.
A dashed line displays as a guide for the message.

4. Move the cursor lower the start of the message to create a downward-slanted diagonal
line. Click to anchor the end of the message on the target object once the diagonal line has
extended itself to that point.

5. If you specified design mode and the specified message is not realized in the model,
Rational Rhapsody asks if you want to realize it. Click OK.

Rational Rhapsody creates a message with the default name message_n(), where n is an
incremental integer starting with 0. Sequence diagrams automatically expand in length to
accommodate new messages.

To specify the type of operation and its access level, select the Features option from the menu. By
default, Rational Rhapsody creates a primitive operation with public access. For more information,
see The Features window.

Rational Rhapsody 681

Sequence diagrams

Message names
The naming convention for messages is as follows:
message(arguments)
The names for messages can be event or operation names. They can include actual parameters in
parentheses, which would be expressions in the scope of the sender/caller. Message names are
resizable, movable text frames. Text wraps to match the contour of the bounding box.

Note: In Rational Rhapsody versions 4.0 and earlier, if you changed the message
name, Rational Rhapsody asked if you wanted to create a new operation with
the given name.
If you modify the name of an operation that exists in the model, the message is automatically
realized to that operation, and Rational Rhapsody changes its type to the type of that operation
(constructor, event, and so on).

If you change the message name to a message that does not belong to the classifier, it becomes
unspecified (in analysis mode).

Displaying message arguments

The SequenceDiagram::General::ShowArguments property displays or hides message
arguments. By default, the ShowArguments property is activated. It applies to all messages in a
sequence diagram, not to individual messages.

Note that any changes you make to property settings apply only to new elements you draw after
making the change, not to existing elements. For example, to have arguments displayed on one
message but not on another message of the same type, set the ShowArguments property before
drawing one message, then reset it before drawing the next message, as shown in this example.

682 User Guide

 Creating sequence diagram elements

Slanted messages
A message drawn on a slant is interpreted as an event if the target is a reactive class, and as a
primitive operation if the target is a nonreactive class. A slanted message emphasizes that time
passes between the sending and receiving of the message. Slanted messages can cross each other.

Horizontal messages
A message drawn as a horizontal line is interpreted as a triggered operation, if the target is a
reactive class, and a primitive operation if the target is a nonreactive class. The horizontal line
indicates that operations are synchronous.

Message-to-self
A message-to-self is interpreted as an event if the instance is a reactive class. If the instance is a
nonreactive class, a message-to-self is interpreted as a primitive operation.

A message-to-self is shown by an arrow that bends back to the sending instance. The arrow can be
on either side of the instance line. If the message-to-self is a primitive operation, the arrow folds
back immediately. If the message-to-self is an event, the arrow might fold back sometime later.

Rational Rhapsody 683

Sequence diagrams

Message line menu

Select Message enables you to select a message. For more information, see Selecting a
message or trigger.
Add Execution Occurrences enables you to add execution occurrences.
Display Options specifies how the element should be displayed.

Modifying the features of a message

The Features window enables you to change the features of a message, including its type or return
value. A message has the following features:

Name specifies the name of the message. The default name is Message_n, where n is an
incremental integer starting with 0.
L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the message, if any. They are enclosed in
guillemets, for example «s1» and enable you to tag classes for documentation purposes.
For information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Message Type specifies the type of message (event, primitive operation, and so on).

Note that you cannot change the message type once the message has been realized.
Sequence specifies the order number of a message. Make sure any numbering sequence
you use, such as 1a., 1b., 1.2.1., 1.2.2., and so on ends with a period (.). Rational
Rhapsody needs the ending period to continue the numbering sequence automatically.
Note: In collaboration diagrams, you can modify both the format of the numbering
and the starting point for the numbering. In sequence diagrams, this field is
read-only. You cannot modify the numbering format or the starting point of the
numbering.
Arguments specifies the arguments for the message.
Return Value specifies the return value of the message.
Realization specifies the class that will be realized. This list contains the following
options:
– Existing classes in project.
– <Unspecified> where if this is an analysis SD, this is the realization setting
for the instance line.
– <New> which opens the Class window so you can set up the new class. For
more information, see Class features.
Click the Features button to open the Features window for the class specified in the
list.

684 User Guide

 Creating sequence diagram elements

In addition, this section lists the sender and receiver objects for the message.

Description describes the message. This field can include a hyperlink. For more
information, see Hyperlinks.

Selecting a message or trigger

When you choose Select Message or Select Trigger, Rational Rhapsody displays a list of the
messages or triggers provided by the target object, as shown in the following figure for messages.
Notice that if there are more messages (or triggers) that can appear on the pop-up menu, a Browse
command displays. For triggers, see also Selecting a trigger transition.

For messages, if the target is an instance of a derived class, the list also includes those message
inherited from its superclass. The target class provides the message, whereas the source class
requires it. You can also think of provided messages as those to which the class responds. At the
implementation level, an event is generated into statechart code that checks for the existence of
that event.

Rational Rhapsody 685

Sequence diagrams

Browsing for messages

The following figure shows the Select Message window that opens when you choose Select
Message > Browse for messages. It shows you all the messages/events that are available.

Cutting, copying, and pasting messages

You can cut, copy, and paste messages in sequence diagrams using the standard Ctrl+X, Ctrl+C,
and Ctrl+V keyboard shortcuts, respectively.

Moving messages
To move a message line:

1. Select the message you want to move.

2. Press Ctrl+Left arrow to move the message to the left, or Ctrl+Right arrow to move it
to the right.

686 User Guide

 Creating sequence diagram elements

Message types
If you open the Features window for the message, you can select the message type: primitive
operation, or triggered operation, or event. Once defined, these messages are displayed in the
browser, denoted by unique icons. In the browser, you can access modify a message by
right-clicking on it and selecting the appropriate option from the menu.

Note
Once a message has been realized, you cannot change its type.

Events
An event is an instantaneous occurrence that can trigger a state transition in the class that receives
it. Because events are objects, they can carry information about the occurrence, such as the time at
which it happened. The browser icon for an event is a lightning bolt.

The following figure shows the Features window for an event.

Note
If an event argument is of type *& (pointer reference), Rational Rhapsody does not generate
code for it.

Rational Rhapsody 687

Sequence diagrams

Triggered operations
A triggered operation can trigger a state transition in a statechart, just like an event. The body of
the triggered operation is executed as a result of the transition being taken. The browser icon for a
triggered operation is a green operation box overlaid with a lightning bolt.

Note
If an argument of a triggered operation is of type *& (pointer reference), Rational Rhapsody
will not generate code for that argument.

Operations
By default, operations are primitive operations. Primitive operations are those whose bodies you
define yourself instead of letting Rational Rhapsody generate them for you from a statechart.

The browser icon for operations is a three-compartment class box with the bottom compartment
filled in:

The icon for the Operations category is black.

The icon for an individual operation is green.

The icon for a protected operation is overlaid with a key.

The icon for a private operation is overlaid with a padlock.

Deleting operations

You delete an operation like any other model element in Rational Rhapsody. However, if you
delete an operation that is realized by a message in a sequence diagram, the message becomes
unspecified (in both design and analysis modes).

If you delete an operation, class, or event, the corresponding message lines are not deleted
automatically from the diagram. To have Rational Rhapsody perform this cleanup
automatically, set the SequenceDiagram::General::CleanupRealized property to Checked.

688 User Guide

 Creating sequence diagram elements

Viewing sequence numbers

If wanted, you can display the sequence number with the message name. The following figure
shows a sequence diagram that includes the sequence number of each operation.

To display the sequence numbers, set the SequenceDiagram::General::ShowSequenceNumber

property to Checked. By default, this property is set to Cleared (sequence numbers are not
displayed).

Rational Rhapsody 689

Sequence diagrams

Creating a reply message

A reply message can realize an operation or event reception at the source (unlike other messages,
which realize operations at the target). By default, reply messages are drawn as unnamed, dashed
lines

690 User Guide

 Creating sequence diagram elements

Animation of the return value for an operation

Note
This feature is not supported in Rational Rhapsody in J.
To show the return value of a function as a reply message in an animated sequence diagram, you
can use one of a number of predefined macros within the code of your function. This means that
the return value for your function visually displays as a reply message on your sequence diagram.
The same is true for a trace of a function.

The following figure shows an animated sequence diagram that draws a return value.

You can use any of the following macros depending on your situation:

OM_RETURN. Use this macro in the body of an operation instead of the regular “return”
statement:
Examples:
– Int Test(int& x) {x = 5; OM_RETURN(10);}
– A* Test() {OM_RETURN(newA());}

Rational Rhapsody 691

Sequence diagrams

CALL. Use this macro if you cannot change the operation code or if you want to animate
return values only on specific calls to the operation. Note that this macro can handle only
primitive types.
Example:
Int test(int n) {return n*5;}
void callingFunction()
{
int v;
CALL (v, f00(10));
// after the call v equals 50
}

CALL_INST. Same as CALL, but use CALL_INST when the return value is of a complex type,
such as a class or a union.
Example:
A* test() {return new A();}
void callingFunction()
{
A *a;
CALL_INST(a, test());
// after the call a equals new A[0]
}

CALL_SER. Use this macro when the type has a user-defined serialization function.
Examples:
– char* serializeMe(A*) {...}
– A* test() {return new A();}
void callingFunction()
{
A *a;
CALL_SER(a, test(), serializeME);}
// after the call v equals <string that serializeMe returns>
}
Note that even if you choose not to embed these macros in your application, you can still see
animated return values by explicitly calling an operation through the Operations window. To call
an operation, click the Call operations tool in the Animation toolbar.

692 User Guide

 Creating sequence diagram elements

Drawing an arrow
An arrow marks when an instance is created. It can originate from the system border or another
instance. It is a horizontal, dotted line from the creator object to the new object. Every object can
have at most one create arrow. You can label the create arrow with construction parameters.

Creating a destroy arrow

A destroy arrow marks the destruction of an object. It is a dotted line from the destroying object to
the object being destroyed. The destroy arrow is red and is not labeled. It can be either a horizontal
line or a message-to-self.

Creating a condition mark

A condition mark (or state mark) is displayed on an instance line. A condition mark shows that the
object has reached a certain condition or is in a certain state. Often, the name corresponds to a state
name in the statechart for an object.

1. Select the condition mark using the Select arrow.

2. Click-and-drag a selection handle to resize the condition mark.

The condition mark remains centered over the instance line. If necessary, other elements on the
sequence diagram are adjusted to accommodate the new size.

Rational Rhapsody 693

Sequence diagrams

Creating a timeout
The notation for timeouts is similar to the notation for events sent by an object to itself. There are
two differences:

A timeout starts with a small box.

The name is a tm(x).
The label on a timeout arrow is a parameter specifying the length of the timeout. Timeouts are
always messages-to-self.

Creating a cancelled timeout

When designing a software system, you can establish waiting states, during which your program
waits for something to occur. If the event occurs, the timeout is canceled. The sequence diagram
shows this with a canceled timeout symbol. If it does not happen, the timeout wakes up the
instance and resumes with some sort of error recovery process. Canceled timeouts are always
messages-to-self.

For example, on a telephone, a dial tone waits for you to dial. The telephone has a timeout set so if
you do not dial, the dial tone changes to a repeating beep. If you do dial, the timeout is canceled.

A canceled timeout occurs automatically once the state on which the timeout is defined is exited.
As a designer, you do not need to do anything to cancel a timeout. The framework has a call to
cancel a timeout, but you do not need to use it because the code generator inserts it automatically.

694 User Guide

 Creating sequence diagram elements

Creating an actor line

An actor line shows where actors affect the sequence diagram. To draw an actor line, drag-and-
drop an actor from the browser to the sequence diagram. An actor is represented as an instance line
with hatching.

When you want to realize a classifier, the list contains all the available classes and actors.

Specifying a time interval

A time interval is a vertical annotation that shows how much (real) time has passed between two
points in the scenario. The name is free text; it is not constrained to be a number or unit of any
kind. Time intervals can only be messages to self.

Rational Rhapsody 695

Sequence diagrams

Creating a dataflow
A dataflow in Rational Rhapsody indicates the flow of data between two instances on a sequence
diagram, as shown in the following figure. Rational Rhapsody animation uses this notation to
represent data flow between flow ports. For information on flow ports, see Flow ports.

Note
This feature is not supported in Rational Rhapsody in J.

The dataflow will be realized to the flow port on the receiving instance. The name of the dataflow
is the name of its realized flow port and the data that has been received. For example, for the
dataflow y = 1, flow port y has received the data 1.

Note that the dataflow arrow can be created through the following ways:

Automatically during the animation of the sequence diagram

Manually by drawing the dataflow on the sequence diagram (that is, click the DataFlow
button and then click the sender and receiver instances).

696 User Guide

 Creating sequence diagram elements

You can double-click the dataflow arrow to open its Features window, as shown in the following
figure, from which you can, for example, choose which flow port to connect to and change the
value to send.

Rational Rhapsody 697

Sequence diagrams

Creating a partition line

Partition lines separate phases of a scenario. They are red lines drawn across the chart and are
usually used to keep parts of the scenario grouped together.

Each partition line includes a note positioned at its left end by default. You can move or resize the
note, but a note is always attached to its partition line. If you move the line, the note follows. Notes
contain the default text “note” until you enter text for them.

Creating an interaction occurrence

An interaction occurrence (or reference sequence diagram) enables you to refer to another
sequence diagram from within a sequence diagram. This functionality enables you to break down
complex scenarios into smaller scenarios that can be reused. Each scenario is an “interaction.”

To create an interaction occurrence:

1. Click the Interaction Occurrence button.

Alternatively, you can use the Add Interaction Occurrence option in the menu.

698 User Guide

 Creating sequence diagram elements

2. Place the reference diagram on one or more instance lines to signify that those classes
interact with the referenced sequence diagram. The interaction occurrence displays as a
box with the “ref” label in the top corner, as shown in this example.

By default, when you first create the interaction occurrence (and have not yet
specified which diagram it refers to), Rational Rhapsody names it using the
convention interaction_n, where n is greater than or equal to 0.

3. Right-click the interaction occurrence and then select Features.

4. Use the Realization list to specify the sequence diagram being referenced. When you
select the referenced diagram, the name of the interaction occurrence is updated
automatically to reflect the name of the referenced SD.

5. Click OK.

You can move, rename, and delete reference sequence diagrams just like regular sequence
diagrams. However, if you delete a sequence diagram that references an interaction occurrence, the
interaction occurrence itself is not deleted, but becomes unassociated.

To change the default appearance of interaction occurrences, use the

SequenceDiagram::InteractionOccurrence properties. See the definition displayed in the
Properties tab for this property.

Navigating to a reference sequence diagram

To navigate to a reference sequence diagram from the current sequence diagram, right-click the
interaction occurrence and select Open Reference Sequence Diagram. The referenced SD is
displayed in the drawing area.

Interaction occurrence menu

Create Reference Sequence Diagram enables you to specify the reference diagram for
the interaction occurrence, if you have not yet specified one
Open Reference Sequence Diagram opens the sequence diagram referred to by the
interaction occurrence
Display Options specifies whether labels are displayed

Rational Rhapsody 699

Sequence diagrams

Part decomposition
Instance line decomposition enables you to easily decompose a instance line on a sequence
diagram into a series of parts. For example, if you have a composite class view in one sequence
diagram and want to navigate to its parts, you can click the composite class and open a
collaboration, which shows how its internal parts communicate for a particular scenario.

Part decomposition is a specialization of an interaction occurrence.

To create a part decomposition:

1. Open the Features window for the instance line. The Classifier Role window opens.

2. Specify the reference sequence diagram using the Decomposed list.

3. Click OK.

In the sequence diagram, the name of the reference sequence diagram is added to the classifier role
label (after the word “ref”), as shown in this example.

As with other interaction occurrences, navigate to the reference SD by right-clicking the instance
line and selecting Open Reference Sequence Diagram.

Limitations
Note the following limitations for decomposition:

UML gates are not supported: use instance lines instead.

Animation is not supported.

700 User Guide

 Creating sequence diagram elements

Creating interaction operators

Interaction operators, which are included in UML 2.0, are used to group related elements in a
sequence diagram. This includes the option of defining specific conditions under which each
group of elements will occur.

Characteristics of interaction operators

Each interaction operator has a type, which determines its behavior, for example Opt, Par, or Loop.

In addition, interaction operators can include a guard to specify specific conditions under which
the path will be taken.

Interaction operators can be nested where necessary.

Adding an interaction operator to a diagram

To add an interaction operator to a diagram:

1. Click the Interaction Operator button on the Diagram Tools.

2. Click the canvas for a default-size interaction operator, or click and drag to draw an
interaction operator of a specific size.

Setting the type of an interaction operator

To set the type of an interaction operator, you can do any of the following actions:

With the interaction operator selected in the diagram, click the type text in the top left
corner and enter the appropriate type.
With the interaction operator selected in the diagram, click the type text and then press
Ctrl+Space and select a type from the list that is displayed.
Open the Features window for the interaction operator, and select a type from the Type
list.

Setting the guard of an interaction operator

To set the guard for an interaction operator, do one of the following actions:

Click [condition] and enter the appropriate expression inside the brackets
Open the Features window for the interaction operator, and type in the expression under
Constraints.

Note
Using Display Options from the context menu, the guards for an interaction operator can be
hidden or shown.

Rational Rhapsody 701

Sequence diagrams

Adding an interaction operand separator to an interaction operator

For certain types of interaction types, you might want to create two subgroups of elements, for
example, if you have two paths that are supposed to be carried out in parallel, or you want to
define two possible paths and a condition that determines which will be followed.

To create an interaction operand separator:

1. Select the Interaction Operand Separator button on the Diagram Tools.

2. Click inside the interaction operator where you would like the division to be.

If necessary, more than one separator can be added to a single interaction operator.

Note
Interaction operators (and interaction operand separators) only appear in the diagram itself.
They do not appear as independent model elements in the browser, nor do they influence
code generation. For this reason, when you display the context menu for an interaction
operator, there is an option to Delete From View but no option for removing from the
model.

Interaction operator types

These are some of the common types of interaction operators:

Alt for (Alternative) multiple fragments; only the one whose condition is true will execute

Opt for (Optional) fragment executes only if the specified condition is true
Par for (Parallel) each of the contained fragments is run in parallel
Loop for the fragment might execute multiple times; guard indicates the basis for iteration

702 User Guide

 Creating sequence diagram elements

Creating execution occurrences

Execution occurrences show the beginning and end of the unit of behavior (the actions performed
by an operation or event) that is triggered by a specific message.

Note
To animate a sequence diagram automatically, set the
SequenceDiagram::General::AutoLaunchAnimation property to one of these options:
Always launches the sequence diagram automatically.
If In Scope launches animation only if the sequence diagram is in the active
component scope.
The Never option for this property prevents automatic animation and is the default.

There are two ways to draw interaction occurrences:

1. Select the message in the sequence diagram, right-click, and select Add Execution
Occurrences.

2. Click the Execution Occurrences button in the Diagram Tools, then select the appropriate
message in the sequence diagram.
You can have Rational Rhapsody create execution occurrences automatically when you create
messages by setting the property
SequenceDiagram::General::AutoCreateExecutionOccurrence to Checked. Execution
occurrences are drawn at the beginning and end of the message.

Note the following information:

If you move a message, its execution occurrences move with it.

You can resize execution occurrences (lengthwise), but cannot move them.

Rational Rhapsody 703

Sequence diagrams

If you move a message with execution occurrences or resize them so they overlap other
execution occurrences, they are “merged,” as shown in this example.

Deleting execution occurrences

You can delete execution occurrences in two ways:

Select the execution occurrence and then click Delete (or use the Delete from Model
option in the menu)
Delete the start message (the message assigned to the execution occurrences). This
automatically deletes the execution occurrences “owned” by that message.

704 User Guide

 Creating sequence diagram elements

Shifting diagram elements with the mouse

You can use the following mouse actions to shift all or some of the elements in a sequence
diagram.

To shift the entire diagram upward or downward:

1. Verify that an instance line is not currently selected.

2. Position the mouse in the area above the classifier role names.

3. Hold down the Shift key and drag the mouse up to shift the entire diagram upward, or drag
down to shift the entire diagram downward.

To shift groups of elements upward or downward.

1. Verify that an instance line is not currently selected.

2. Position the mouse above the highest element that you want to shift.
3. Hold down the Shift key and drag the mouse up to shift the element and all the elements
below it upward, or drag down to shift the element and all the elements below it
downward

To shift groups of instance lines to the left or right:

1. Select any of the instance lines in the diagram.

2. Position the mouse to the left of the instance lines that you want to shift.

3. Hold down the Shift key and drag the mouse to the right to move all the elements on the
right side of the mouse cursor to the right. Hold down the Shift key and drag the mouse to
the left to move all the elements on the right side of the mouse cursor to the left.

Note: If you place the mouse on an instance line and drag while the Shift key is held
down, Rational Rhapsody will shift the instance lines on the right of that
instance line but not that instance line itself. “On an instance line” includes the
entire width below the box that contains the name of the classifier role.

Rational Rhapsody 705

Sequence diagrams

Display options
Most of the elements that can be added to a sequence diagram have options that you can set to
affect how they are displayed in the diagram. While these options vary from element to element,
the following options are common to the System Border, Instance Line, Message, and Reply
Message elements:

Select whether to display the name or the label of the element

Show/hide any applied stereotypes

Sequence diagrams in the browser

The browser icon for sequence diagrams consists of two instance lines with messages passing
between them. If the diagram is a unit, the icon has a small gray file overlay.

To open the menu for a sequence diagram, right-click the name of the diagram. The menu contains
the following options:

Open Sequence Diagram opens the selected sequence diagram in the drawing area.
Features opens the Features window for the sequence diagram.
Features in New Window opens the Features window for the sequence diagram in a
separate window.
Add New enables you to add a new dependency (see Dependencies), annotation (see
Annotations for diagrams), hyperlink (see Hyperlinks), or tag (see Use tags to add element
information).
References enables you to search for references to the diagram in the model (see Finding
element references).
Unit enables you to either make the sequence diagram a unit that you can add to a CM
archive (Save) or modify an existing unit (Edit Unit).
Configuration Management provides access to common CM operations for the sequence
diagram, including Add to archive, Check In, Check Out, Lock, and Unlock.
Format changes the format used to draw the element (color, line style, and so on). For
more information, see Change the format of a single element.
Delete from Model deletes the sequence diagram from the entire model.

706 User Guide

 Animation for selected classes

Animation for selected classes

As part of the reverse engineering workflow, you might want to animate selected classes without
the defining configurations. To accomplish this, after reverse engineering create one or more
sequence diagrams, drag reverse engineered classes onto these diagrams, and select the ones to
animate. The resulting animation shows the communication between the selected classes.

Sequence diagram comparison

During the development process, sequence diagrams (SDs) are used for the following primary
purposes:

In the early system requirements phase, they are used for use case description.
In the implementation phase, they verify that all conditions are met in terms of
communication between classes.
In the testing phase, they capture the actual system trace.
Therefore, there is a need to facilitate comparison between SDs because, in principle at least, they
should be identical. The execution message sequence should match the specification message
sequence. The Sequence Diagram Comparison tool enables you to perform comparisons, for
example between hypothetical and actual message sequences. You could also use this tool to
compare two runs for regression testing.

If all execution SDs are identical to their corresponding specification (nonanimated) SDs, the
system satisfies the requirements as captured in the use cases. However, if there are differences,
you need to determine whether the specification was inaccurate or an error exists in the
implementation. In both cases, you should correct the modeling error (either in the statechart or the
SD) and then repeat the testing cycle to determine whether you have fixed the problem.

Sequence comparison algorithm

When comparing sequences, the following message parameters are used to determine whether the
messages in the two SDs are identical:

Departure time
Arrival time
Arguments
One simple approach involves comparing the exact position of every message and stopping at the
first difference. However, this is probably too naive a comparison. For example, if there is a time
offset in one SD, this kind of comparison would stop at the first message.

Rational Rhapsody 707

Sequence diagrams

A more useful approach, therefore, is to take all events (message departures and arrivals) in order,
and compare them without using the exact time. This kind of comparison, although simple, still
shows when two SDs are essentially identical.

Because some messages can be “noise,” the comparison algorithm should also be able to decide
whether a message is legitimate, and if not, mark it and continue with the comparison starting with
the next message.

The point in comparing two SDs is not to show when one sequence is identical to another, but
rather where and why they are different. Therefore, yes/no answers are not sufficient. Proper
results must detail precisely what is identical and what is different. This is the approach that
Rational Rhapsody takes when comparing message sequences.

Comparing sequence diagrams

Once you have saved two SDs illustrating the same scenario, for example, a specification and an
execution version or two subsequent runs to test for regression, you are ready to start the sequence
comparison.

To start the comparison:

1. Select Tools > Sequence Diagram Compare. The Sequence Diagrams Comparison
window opens, as shown in the following figure.

2. Using the SD1 and SD2 list controls, select two sequence diagrams to compare.

3. Set options for the sequence comparison as wanted. See Sequence comparison options.

4. When all options are set and you are ready to start the comparison, click OK.

708 User Guide

 Sequence diagram comparison

The result of the comparison displays as a dual-pane window with the diagram selected for SD1 on
the left, and the diagram selected for SD2 on the right. Both panes are read-only. The following
figure shows sample results.

The messages displayed in both panes are color-coded based on the comparison results. The
following table lists the color conventions used in the comparison.

Arrow Color Name Color Description

Green Blue Message matches in both SDs
Pink Pink Message is missing in the other SD
Green Pink Message has different arguments in the other SD
Orange Orange Message arrives at a different time in the other SD
Gray Gray Message was excluded from comparison

Rational Rhapsody 709

Sequence diagrams

Sequence comparison options

Specification Sequence Diagrams show only one specific thread from the mind of the designer.
Therefore, certain instances and messages will be missing. On the other hand, execution
(animated) Sequence Diagrams reflect the full collaboration between objects. This is why the
simple comparison between specification and execution Sequence Diagrams always fails. Rational
Rhapsody provides various options that enable you to compensate for some of the necessary
differences between the two kinds of diagrams when doing a sequence comparison.

Select Options in the Sequence Diagrams Comparison window to open the Sequence Diagram
Comparison options window. This window contains the following tabs:

The General tab for the sequence comparison

The Message Selection tab

The Instance Groups tab

The Message Groups tab

The following sections describe how to use these tabs in detail.

The General tab for the sequence comparison

The General tab allows you to specify whether to use synchronization and to save or upload your
option settings. The tab contains the following fields:

Synchronization specifies whether to ignore the arrival times of messages. For more
information, see Ignoring message arrival times.
Save saves your option settings to a file that you can reuse. For more information, see
Saving and loading options settings.
Load loads your option file. For more information, see Saving and loading options
settings.

Ignoring message arrival times

Sometimes the order of arriving messages is insignificant. The Synchronization option enables
you to ignore the arrival times of messages and consider only the order in which they are sent.

In the resulting comparison display, equivalent messages are vertically synchronized in the
adjacent window panes. This helps you to locate corresponding messages in both diagrams.

To enable or disable the synchronization option, select or clear the Synchronization box in the
General tab.

710 User Guide

 Sequence diagram comparison

Saving and loading options settings

You can save your options settings to a file and then reload them for subsequent message
comparisons.

To save the settings:

1. Click the Save button on the General tab.

2. The Save As window opens. The default name for the options file is composed of the first
words of the titles of each of the diagrams being compared separated by an underscore:
<SD2>_<SD1>.sdo
The file extension .sdo stands for Sequence Diagram Options. If wanted, edit the
path and default name for the options file.

3. Click OK.

To reload your option settings:

1. In the General tab, click Load. The Open window is displayed.

2. Select the .sdo file that contains your option settings.

3. Click Open.

The sequence comparison options are restored to the settings last saved in the file.

Rational Rhapsody 711

Sequence diagrams

The Message Selection tab

The Message Selection tab, shown in the following figure, enables you to select which messages
to include and whether to include arguments in the comparison.

On this Message Selection tab, the word “Ignore” is the default setting for the Arguments column
for all messages. This means that, by default, argument comparison is ignored for messages.

Using this tab, you can:

Exclude a message from the comparison (see Excluding a message in the comparison)
Compare arguments (see Comparing arguments)

712 User Guide

 Sequence diagram comparison

Excluding a message in the comparison

Specification SDs typically include information that is essential to a particular use case or
scenario. In many cases, they exclude the initialization phase messages, whereas execution SDs
include all messages. Therefore, it might be necessary ignore certain messages when doing a
comparison, such as constructors. Ignored messages are inaccessible in the resulting comparison
window.

To exclude a message from the comparison:

1. Select the message to exclude.

2. Click Edit. The Edit Message Compare Options window opens.

3. Click the Ignore box to exclude the message from the comparison.

4. The three radio buttons, allow you to specify the way to treat Arguments associated with
the selected message.

5. Click OK.

Comparing arguments
There are two options for determining whether messages are identical: the first is to compare the
message names and all arguments, the second is to compare only the message names. The latter
option is more useful because SDs show four different kinds of arguments:

Unspecified arguments
Actual values
Formal names
Both names and values
In specification SDs, you might not always provide complete information about message
arguments. Because execution SDs record what the system actually does, they always show both

Rational Rhapsody 713

Sequence diagrams

argument values and names. Therefore, the message comparison ideally should not use arguments
but rather focus primarily on message names.

When two messages are named identically, you can compare their arguments.

For example, consider messages called evDigitDialed(Digit). They would be equivalent if you
compared only their argument names (Digit). However, if you compared their values
(EvDigitDialed(Digit=0), EvDigitDialed(Digit=1), and so on), their argument values would
not be equivalent.

Argument comparison occurs in the following steps:

1. Find each argument.

2. Find the argument name and value.

3. Determine whether to use the name, the value, or both for the comparison.

To specify whether to use argument names or values:

1. In the Message Selection tab, select a message and click Edit. The Edit Message
Compare Options window opens.

2. Select one of the following options:

Compare Names Only compares argument names, but ignore their values.
Compare Names and Values compares both argument names and values.
These are commonly used settings:

Specification SD Execution SD Value

Message() Message(Arg = 1) Ignore Arguments
Message(Arg) Message(Arg = 1) Compare Names Only
Message(1) Message(Arg = 1) Compare Names and Values

3. Click OK.

Depending on your selections, the following labels are displayed in the Arguments
column on the Message Selection tab:

Disable means messages for which arguments should be ignored

Name means messages for which argument names should be compared, but not
the argument values
Value means messages for which both argument names and values should be
compared

714 User Guide

 Sequence diagram comparison

The Instance Groups tab

In specification SDs, all messages sent by the environment come from specific objects. In
execution SDs, however, these messages could potentially come from you interacting with the
animation. This difference can impair the comparison.

In general, requiring a complete object match between execution and specification SDs is too
rigorous a requirement. The solution is to associate objects in one SD with other objects in the
other SD. Messages can then match if their source and target objects are associated in both SDs.

To associate objects with each other you create object groups. Object groups are, in essence,
instance abstractions that bridge the gap between high-level use cases and actual implementation,
or between black-box and white-box scenarios. Using object groups, you can then compare objects
that do not have the same name, or compare one object to several other objects.

Rational Rhapsody 715

 Sequence diagrams

To view object groups, select the Instance Groups tab in the Sequence Diagram Comparison
options window. The Instance Groups tab, shown in the following figure, displays a list of the
existing object groups in the model. There is one object group for each object, which is, by default,
the only member of its own group.
.

The objects that belong to the group are displayed in the Objects groups list at the bottom of the
window. This means that the objects listed for SD1 are considered logically the same as those
listed for SD2.

The Instance Groups tab enables you to perform the following operations:

Add creates a new object group (see Creating object groups)

Delete deletes an object group (see Deleting object groups)
Edit modifies an existing object group (see Modifying object groups)
Set to Default resets an object group (see Resetting object groups)
Delete All deletes all object groups (see Deleting object groups)

716 User Guide

 Sequence diagram comparison

Creating object groups

To create a new instance group:

1. On the Instance Groups tab, click Add. The Edit Object Group window opens. The
default name for new object groups is ClassBuffn, where n is an integer starting with 1.

2. If wanted, edit the name of the new object group.

3. To add objects to the group, move one or more unused objects from either of the boxes on
the right to the corresponding box on the left.
4. Click OK.

Deleting object groups

To delete an existing object group:

1. On the Instance Groups tab, select the object group you want to delete.

2. Click Delete.
3. Click OK.

Any objects that belonged to the deleted group are now unused and available to be assigned to
another object group.

To delete all instance groups:

1. On the Instance Groups tab, click Delete All.

2. Click OK.

All objects are now unused and available to be assigned to a new object group.

Rational Rhapsody 717

Sequence diagrams

Modifying object groups

If you want to associate different objects than the ones shown, either move one or more of the
objects to a different object group or create a new group. In either case, you first need to remove
the object you are moving from the group it is currently in, because an object can only belong to
one group at a time.

To remove an object from a group:

1. On the Instance Groups tab, select an object group.

2. Click Edit. The Edit Object group window opens.

The name of the selected object group is displayed at the top of the window. The
name box is unavailable because you cannot edit it here.

The Edit Object Group window contains four boxes. The two on the left show which
objects in SD1 will be associated with which objects in SD2. The two boxes on the
right show which objects in each diagram are currently not assigned to any group,
and are therefore available to be assigned to a group.

3. Select an object in one of the boxes on the left and click the right arrows button.

718 User Guide

 Sequence diagram comparison

To add an object to the group:

1. Select an object in one of the boxes on the right, and move it with the left arrows button.

2. Click OK. The selected object in one diagram is now available to be added to another
group.

3. On the Instance Groups tab, select the new group for the object and click Edit.

4. Select the object in the Unused Objects in SD<number> box in the lower, right corner
and click the left arrows key to add it to the group.

5. Select the object in the To Objects in SD<number> box in the lower, right corner and
click the right arrows button to remove it from the group.

6. Click OK.

Resetting object groups

To set all object groups back to the default of one group per object, click Set to Default on the
Instance Groups tab. An object group is added for each object with the same object in SD1 and
SD2 belonging to the group.

Rational Rhapsody 719

Sequence diagrams

The Message Groups tab

In specification SDs, you often must assume how the message queue works to determine the
sequence of messages. It is highly likely that in specification SDs the order of messages will be
different than the actual one specified in the statechart. An incorrect ordering assumption can
result in large mismatch.

To avoid this problem, the comparison must be able to ignore the timing of messages. For
example, a message M1 sent by an instance A1 after a message M2 sent by an instance A2 could
match the same message sent before M2:

A1 A2 A3 A1 A2 A3
M2 M1

M1 M2
=

There can also be cases where two or more messages should be sent at the same time, but the order
is not important. Message groups enable you to specify groups of messages for which ordering is
not important. There is a match if any message in the group occurs in any order.

720 User Guide

 Sequence diagram comparison

The Message Groups tab, shown in the following example, enables you to create, modify, and
delete message groups.

Rational Rhapsody 721

Sequence diagrams

Creating message groups

To create a message group:

1. On the Message Groups tab, click Add. The Edit Message Group window opens.

The default name for new message groups is MessageBuffn, where n is an integer
starting with 0.

2. If wanted, edit the name of the new message group.

The Edit Message Group window contains two list boxes: the left one shows the messages
that currently belong to message group, whereas the right one shows all messages in the
two SDs being compared. Messages can belong to more than one message group.

Adding a message to a message group

To add a message to the message group:

1. On the Message Groups tab, click Add.

2. Select a message from the All Messages list and click the left arrows button to move it to
the Messages in group list. For multiple selections, use Shift+Click or Ctrl+Click.

3. Click OK.

722 User Guide

 Sequence diagram comparison

Removing a message from a message group

To remove a message from the message group:

1. On the Message Groups tab, click Add.

2. Select a message from the Messages in group list and click the right arrows button to
move it to the All Messages list. For multiple selections, use Shift+Click or Ctrl+Click.

3. Click OK.

Determining the message group members

To see which messages belong to a message group:

1. On the Message Groups tab, select a message group from the list.

The messages that belong to that group are listed at the bottom of the window, as shown in
this example.

2. Click OK.

Rational Rhapsody 723

Sequence diagrams

Modifying message groups

To modify an existing message group:

1. On the Message Groups tab, select a message group from the list and click Edit. The Edit
Message Group window opens.

2. Select a message in the Messages in group list and click the right arrows button to remove
it from the group.

Select a message in the All Messages list and click the left arrows button to add it to the
group.

3. Click OK.

Deleting message groups

To delete an existing message group:

1. In the Sequence Diagram Comparison options window, select the message group to delete.

2. Click Delete.

3. Answer OK to the confirmation prompt.

724 User Guide

 Statecharts

Statecharts define the behavior of objects by specifying how they react to events or operations.
The reaction can be to perform a transition between states and possibly to execute some actions.
When running in animation mode, Rational Rhapsody highlights the transitions between states.

Statecharts define the run-time behavior of instances of a class. A state in a statechart is an

abstraction of the mode in which the object finds itself. A message triggers a transition from one
state to another. A message can be either an event or a triggered operation. An object can receive
both kinds of messages when sent from other objects. An object can always receive events it sends
to itself (self-messages). In Rational Rhapsody, statecharts are part of the object-oriented
paradigm. The more complicated classes can have statecharts; simpler classes do not require them.

You can use operations and attributes in classes with statecharts to define guards and actions, as in
the following example.

Rational Rhapsody 725

Statecharts

States
A state is a graphical representation of the status of an object. It typically reflects a certain set of its
internal data (attributes) and relations. In statecharts, states can be broken down hierarchically as
follows:

Basic (leaf) state is a state that does not have any substates.
Or state is a state that can be broken down into exclusive substates. This means that the
object is exclusively in one or the other of its substates.

In the following example, there are possible two states: On and Off.

And state An object is in each of its substates concurrently. Each of the concurrent
substates is called an orthogonal component. You can convert an Or state to an And state
by dividing it with an And line. For more information, see And lines.

You set the statechart implementation in the Settings tab of the Configuration window in the
browser.

726 User Guide

 Opening an existing statechart

Opening an existing statechart

To open an existing statechart in the drawing area:

1. Click the appropriate button in the Diagrams toolbar to the Open Statechart window
opens for you to select the diagram.
2. For statecharts, select the class that the diagram describes from the list of available
diagrams. For all other diagrams, select the diagram you want to open.

3. Click OK. The diagram opens in the drawing area.

As with other Rational Rhapsody elements, use the Features window for the diagram to edit its
features, including the name, stereotype, and description. For more information, see The Features
window.

Statechart drawing tools

The Diagram Tools for a statechart includes the following tools:

Drawing
Name Description
Tool
State Indicates the current condition of an object, such as On or Off. For more information,
see States.

Transition Represents a message or event that cause an object to transition from one state to
another. For more information, see Transitions.

Initial connector Shows the default state of an object when first instantiated. For more information,
see Initial connectors.

Add line Separates the orthogonal components of an And state. There can be two or more
orthogonal components in a given And state and each behaves independently of the
others. For more information, see And lines.
Decision Node Shows the branches on transitions, based on Boolean conditions called guards. For
more information, see Decision nodes.

History Stores the most recent active configuration of a state. An transition to a history
connector connector restores this configuration. For more information, see History
connectors.
Termination Ends the life of the object. For more information, see Termination connectors.
connector
Merge Node Joins multiple transitions into a single, outgoing transition. For more information, see
Merge nodes.

Rational Rhapsody 727

Statecharts

Drawing
Name Description
Tool
Diagram Joins physically distant transition segments. Matching names on the source and
connector target diagram connectors define the jump from one segment to the next. For more
information, see Diagram connectors.
EnterExit point Represents the entry to / exit from sub-statecharts. For more information, see
EnterExit points.

Join node Merges multiple incoming transitions into a single outgoing transition. For more
information, see Activity diagrams.

Fork Node Separates a single incoming transition into multiple outgoing transitions. For more
information, see Activity diagrams.

Transition Label Add or modify a text describing an transition.

Termination Signifies either local or global termination, depending on where they are placed in
State the diagram.

Dependency Indicates a dependent relationship between two items in the diagram. For more
information, see Activity diagrams.

Send Action Represents the sending of events to external entities. For more information, see
Send action elements.

The following sections describe how to use these tools to draw the parts of a statechart. For basic
information on diagrams, including how to create, open, and delete them, see Graphic editors.

Drawing a state
To draw a state:

1. Click the State button in the Diagram Tools.

2. Click-and-drag or click in the drawing area to create a state with a default name of
state_n, where n is an incremental integer starting with 0.

3. If wanted, change the state name, then press Enter.

States include a standard name compartment.

State name guidelines

When naming states, follow these guidelines:

Must be identifiers.

728 User Guide

 Drawing a state

Do not include spaces, “My House” is not valid. Use “MyHouse.”

Must be unique among sibling states.
Should not be the same as the names of any events or classes in the model.

Features of states
The Features window allows you to add and change the features for a state. A state has the
following General tab features:

Name specifies the name of the state.

L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the state, if any. They are enclosed in guillemets, for
example «s1» and enable you to tag classes for documentation purposes. For information
on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.

Action on entry
The Action on Entry specifies the action that should be executed whenever the system enters this
state, regardless of how the system arrived here.

If the action on entry value is overridden, the Overridden check box is checked. The Overridden
check box is available in the Features windows for textual information in statecharts (state entry
and exit actions, and guards and actions for transitions and static reactions). By enabling or
disabling this check box, you can easily override and unoverride statechart inheritance without
actually changing the model. As you toggle the check box on and off, you can view the inherited
information in each of the window fields, and can decide whether to apply the information or
revert back to the currently overridden information. For more information, see Overriding textual
information.

Action on exit
The Action on Exit specifies the action that should be executed whenever the system exits this
state, regardless of how the system exits.

If the action on entry value is overridden, the Overridden check box is checked.

Rational Rhapsody 729

Statecharts

Reactions in state
The Reaction in State specifies the trigger, guard, and actions identified in an transition label. If the
trigger occurs and the guard is true, the action is executed. For more information, see Adding or
modifying activity flow labels. Use the appropriate window button:

New creates a new reaction in state. If you select this option, the Reaction Features
window opens so you can specify the Trigger, Guard, and Action for the new reaction.
Edit modifies an existing reaction.
Delete deletes a reaction.
Note: If you specify action on entry or exit behavior for a state, this icon is added to
the state display.

730 User Guide

 Drawing a state

Display options for states

Using the Display Options option in the menu, you can specify whether:

States are displayed with a name or label.

Stereotypes are displayed with a name, label, or icon.
The exit and entry actions are displayed.
The display for the quickMode state includes its entry and exit actions.

Rational Rhapsody 731

Statecharts

Termination states
A termination state provides local termination semantics. Local termination implies the
completion of a composite state without the destruction of the context instance.

There are two different modes for local termination:

Statechart mode where local termination applies only to composite states with final
activities inside them.
Activity diagram mode where local termination applies to every block and composite
state, even those that do not have internal final activities. (This is the UML statechart/
activity diagram-supported mode.)
The CG::Statechart::LocalTerminationSemantics property specifies whether activity
diagram mode of local termination is available. The default value of Cleared means that the
activity diagram mode of local termination is unavailable (statechart mode is active).

Local termination code with the reusable statechart implementation

The following sections describe how code is generated to support local termination when you use
the reusable statechart implementation.

Or states in reusable statechart

Code is generated for local termination of Or states with the reusable statechart implementation as
follows:

For each final activity, a Concept class data member of type FinalState is generated. A
new class is not created as for other state types.
The following local termination guard is added to each outgoing null transition from an Or
state that needs local termination semantics:
&& IS_COMPLETED(state)
If an Or state has several final activities, an outgoing null transition is activated when any
one of them is reached. However, the specific connector is instrumented.
The isCompleted() function is overridden for an Or state that has a final activity,
returning True when the final activity is reached. The function is also overridden for an
Or state without a final activity in activity diagram mode, always returning False.
An instance of a FinalState is created by a line similar to the following example:
FinalA = new FinalState(this, OrState, rootState,
“ROOT.OrState.FinalA”);

732 User Guide

 Termination states

And states in reusable statechart

Code is generated for local termination of And states with the reusable statechart implementation
as follows:

The following local termination guard is added to each outgoing null transition from an
And state if one of the components has a final activity:
&& IS_COMPLETED(AndState)
In this case, the isCompleted() function of the AndState framework class is called.

The following local termination guard is added to a join transition for each Or state that is
a source of the transition:
&& IS_COMPLETED(state)

If a source state of a join transition is a simple state (leaf state), its guard is as follows:
(IS_IN(state))
The following example shows the code generated for a join transition with a real guard and local
termination guards, where C1 and C2 are Or states with final activities and C3 is a leaf state:
if(RealGuard() && IS_COMPLETED(C1) && IS_COMPLETED(C2) && IS_IN(C3))

Local termination code with flat statechart implementation

The following sections describe how code is generated to support local termination when the flat
statechart implementation is used.

Or states in flat statechart

Code is generated for local termination of Or states with the flat statechart implementation as
follows:

For each final activity, the new state enumeration value is generated (as for a regular
state).
For each Or state with a final activity, a <StateName>_isCompleted() operation is
generated. This operation returns an OMBoolean value of True when the state is
completed. If the CG::Class::IsCompletedForAllStates property is Checked, the
operation is generated for all states.

The following example shows the code generated for a <StateName>_isCompleted()

operation where FinalA and FinalB are final activities in the Or state:
inline OMBoolean
class_0::OrState_isCompleted() {
return (FinalA_IN() || FinalB_IN());
}

The following local termination guard is added to each outgoing null transition from an Or
state that needs local termination semantics:

Rational Rhapsody 733

Statecharts

&& IS_COMPLETED(state)

Instrumentation information for FinalState is generated in the transition code (as for
normal states).

And states in flat statechart

Code is generated for local termination of And states with the flat statechart implementation as
follows:

The following local termination guard is added to each outgoing null transition from an
And state if one of the components has a final activity.
&& IS_COMPLETED(AndState)
In this case, the isCompleted() function of the AndState framework class is called:

The isCompleted() operation of AndState calls the IS_COMPLETED() macro for all
components that have a final activity. This operation returns TRUE only when all
components are completed. If an And state does not have components with a final
activity, the operation returns TRUE in statechart mode and FALSE in activity diagram
mode.

The following example shows the <StateName>_isCompleted() function generated for

an And state named AndState, with two components, Component1 and Component2, each
of which has a final activity:
OMBoolean class_0::AndState_isCompleted()
{
if(IS_COMPLETED(Component1) == FALSE)
return FALSE;
if(IS_COMPLETED(Component2) == FALSE)
return FALSE;
return TRUE;
}

Implementation of join transitions with the flat statechart implementation is the same as
for the reusable statechart implementation (see And states in reusable statechart).

734 User Guide

 Transitions

Transitions
A basic transition is composed of a single arrow between a source and a destination. Transitions
represent the response to a message in a given state. They show what the next state will be, given a
certain trigger. A transition can have a trigger, guard, and actions.

The transition context is the scope in which the message data (parameters) are visible. Any guard
and action inherit the context of an transition determining the parameters that can be referenced
within it.

The source of an transition can be one of the following items:

State
Initial connector
History connector
The destination of an transition can be one of the following items:

State
Final activity
History connector

Creating a statechart transition

To draw a statechart transition:

1. Click the Transition button in Diagram Tools.

2. Click the bottom edge of the state to anchor the start of the transition.

3. Move the cursor to the top edge of the state and click to anchor the transition line.

4. In the label box, type the name of the event. Press Ctrl+Enter to terminate.

Note
Pressing Enter in an transition name, without simultaneously pressing Ctrl, simply adds a
new line.

Rational Rhapsody 735

Statecharts

Features of transitions
Use the Features window to add and change the features for a transition, as shown in this example.

An transition has the following General tab features:

Name specifies the name of the transition.

L specifies the label for the element, if any. For information on creating labels, see
Descriptive labels for elements.
Stereotype specifies the stereotype of the element, if any. They are enclosed in guillemets,
for example «s1» and enable you to tag classes for documentation purposes. For
information on creating stereotypes, see Stereotypes.
Note: The COM stereotypes are constructive; that is, they affect code generation.
Target specifies the target of the transition. This field is read-only.
Trigger specifies the trigger for the transition. See Triggers.

736 User Guide

 Transitions

Guard specifies the guard for an transition.

The Overridden check box is available in the Features windows for textual information
in statecharts (state entry and exit actions, and guards and actions for transitions and static
reactions). By enabling or disabling this check box, you can easily override and
unoverride statechart inheritance without actually changing the model. As you toggle the
check box on and off, you can view the inherited information in each of the window
fields, and can decide whether to apply the information or revert back to the currently
overridden information. For more information, see Overriding textual information.
Action specifies the transition action.

Rational Rhapsody 737

Statecharts

Types of transitions
You can create the following types of transitions:

Compound transitions
Forks
Joins

Compound flows
A compound flow is composed of several transition segments connected by intermediate nodes. A
transition segment is a subpart of a transition between any source, destination, or intermediate
nodes.

The intermediate nodes can be any of the following items:

Forks

Joins

Merge nodes

Decision nodes

Diagram connectors
In semantic terms, forks and joins can both be nodes.

738 User Guide

 Transitions

Forks
A fork is a compound transition that connects a transition to more than one orthogonal destination.
The destination of a fork segment can be a state, final activity, or connector. However, it cannot
have a label, as shown in the this example.

Joins
A join is a compound transition that merges segments originating from states, final activities, or
connectors in different orthogonal components. Rational Rhapsody automatically generates a join
when you combine source segments. The segments entering a join connector should not have
labels, as shown in the following figure.

Note
If the model contains joins from more than two concurrent states, this generates an error. This is a
Rational Rhapsody limitation in that the error is a violation of MISRA rule 33.

Rational Rhapsody 739

Statecharts

Selecting a trigger transition

For a list of transitions defined in the diagram, right-click a transition line in the diagram and select
Select Trigger. The pop-up menu that displays lets you select one of the available triggers,
including inherited triggers, that have already been defined for the class.

Notice that if there are more triggers that can appear on the pop-up menu, a Browse command
displays. Click Browse to open the Select Trigger window that shows you all the triggers that are
available.

See also Selecting a message or trigger.

740 User Guide

 Transition labels

Transition labels
Transition labels can contain the following parts:

Triggers

Guards

Actions
The syntax for transitions is as follows:
trigger [guard] /action
The following example shows a transition label consisting of a timeout trigger (see Timeouts), a
guard, and an action:
tm(500)[isOk()]/printf("a 0.5 second timeout occurred\n")
In this example, the trigger is the timeout tm(500) and the guard is [isOk()]. The action to be
performed if the trigger occurs and the guard is true is printf("a 0.5 second timeout
occurred\n").

All three parts of the transition are optional. For example, you can have a transition with only a
trigger and an action, or only a guard. The following example shows a transition label consisting of
only a trigger and an action:
clockw /itsEngine->GEN(start)
When typing a multiline transition label (for example, one that has several actions separated by
semicolons), you can press Ctrl+Enter to advance the cursor to the next line and continue the
label.

Triggers
Every transition is associated with a designated message, which is the trigger of the transition. In
other words, the trigger of the transition is waiting for its event. A transition cannot be associated
with more than one message. Triggers can be events, triggered operations, or timeouts.

Events are asynchronous; time can pass between the sending of the event and when it actually
affects the statechart of the destination. Triggered operations are synchronous; their effect on the
statechart of the destination is immediate.

This not a valid transition label:

e1 or e2
The trigger part of a transition label cannot use conditional expressions; however, guards can.

Rational Rhapsody 741

Statecharts

Events
Events originate in the analysis process as “happenings” within the system to which objects
respond. Their concrete realizations are information entities carrying data about the occurrence
they describe.

For designers, an event is a one-way, asynchronous communication between objects or between

some external interface and the system (see Events and operations).

The following figure shows an event.

You can specify an event using the following methods:

An event name
The name of a triggered operation
tm(time expression)

For timeout events, the time expression must be an integer

expression, in milliseconds.

Event usage
Classes and their statecharts can receive events defined in any package in the model. Cross-
package inheritance of statecharts for reactive classes is not allowed.

Event class hierarchy

An event is an instance of a particular event-class. Events can be subclassed to add attributes
(event parameters). The base class for all events is OMEvent.

For example, windowing systems define several event classes: MouseEvent is a subclass of
InputEvent, and MouseClickEvent and MouseMotionEvent are subclasses of MouseEvent.

To make an event a subclass of another event:

1. Open the Features window for the event.

2. From the Inherits: list, select the event that is to serve as the base class.

3. Click Apply or OK.

742 User Guide

 Transition labels

Generating events
You generate an event by applying a gen method on the destination object, as follows:
client->gen(new event(p1,p2,...,pn))
The generate method queues the event on the proper event queue.

The framework provides a GEN macro, which saves you from having to use the new operator to
generate an event. For example:
client->GEN(event(p1, p2, pN))

Event semantics
An event is created when it is sent by one object to another, then queued on the queue of the target
object thread (thread partitioning is not covered in this guide). An event that gets to the head of the
queue is dispatched to the target object. Once dispatched to an object, it is processed by the object
according to the semantics of event propagation in statecharts and the run-to-completion
semantics. After the event is processed, it no longer exists and the execution framework implicitly
deletes it.

Internal events
An internal event occurs when an object sends a message to itself. To create an internal event, omit
the destination object from the send operation, as follows:
GEN(warmEngine(95))

Private events
You can control which classes can generate events to which classes using friendship. In this way,
you can ensure that events come from trusted classes only. The event request and queueing
function is controlled by the gen() methods, which are public by default in the framework base
class OMReactive. If you want to control the generation of events using friendship, make the first
gen() method in Share\oxf\OMReactive.h protected. This is a one-time effort. Do not change
the second gen() method, which is used for instrumentation.

Inside each application class, grant friendship to the classes that need to generate events for it. If
you do not grant friendship, your program will no longer compile.

Rational Rhapsody 743

Statecharts

Adding operations to an event

Rational Rhapsody allows you can add operations to events you have defined. This allows you to
add additional behavior to your events.

To add an operation to an event, right-click the event in the browser and select Add New >
Operation.

The new operation displays below the event in the browser, and when code is generated, the
operation displays in the class that represents the event.

Note
Roundtripping does not bring into the model any new operations that you have added to
event classes in your code, nor does it bring into the model changes that were made directly
to the body of operations that were previously created for events.

Events as attribute types

Events can be used as types for attributes.

744 User Guide

 Transition labels

Triggered operations
Triggered operations are services provided by a class to serve other classes. They provide
synchronous communication between a client and a server object. Because its activation is
synchronous, a triggered operation can return a value to the client object.

Unlike events, operations are not independent entities; they are part of a class definition. This
means that operations are not organized in hierarchies.

The usage of operations corresponds to invocation of class methods in C++. There are three
reasons why operations have been integrated with the statechart framework:

They allow use of statecharts in architectures that are not event-driven to specify
behaviors of objects in the programming sense of operations and object state.
They provide for late design decisions to optimize execution time and sequencing by
converting event communication into direct operation invocations.
They allow the description of behaviors of (primitive) “passive” classes using statecharts.

Applying a triggered operation

A triggered operation is started in the same way as a primitive operation:
server->operation(p1, p2, ..., pn)
Or:
result = server->operation(p1, p2, ..., pn)

Operation replies
Operations can return a value. The return value for an operation m must be determined within the
transition whose context is the message m, using the reply operation:
m/reply(7);

Note
A triggered operation might not result in another triggered operation on the same instance.

Making sure a triggered operation is called

There might be a problem with the reply from triggered operations if the receiver object is not in a
state in which it is able to react to a triggered operation. If a triggered operation is called when not
expected, incorrect return values might result.

Rather than use the IS_IN macro to determine what state the receiver is in, you can design your
statechart so the triggered operation is never ignored. To do this, create a superstate encompassing
the substates in the object, and in the superstate create a static reaction with a trigger to return the

Rational Rhapsody 745

Statecharts

proper value. For example, to make sure that a sensor is always read regardless of what state an
object is in, create a static reaction in the superstate with the following transition:
opRead/reply(getStatus())
This way, no matter what substate the object is in, it will always return the proper value. Although
both the trigger to the superstate and that to a substate are active when in a substate, the trigger on
the transition to the superstate is taken because it is higher priority. See Transition selection.

Timeouts
Timeout triggers have the syntax tm(<expression>), where <expression> is the number of time
units. The default time unit is milliseconds. The time units are set based on the operating system
adapter implementation of the tick timer. A timeout is scheduled when the origin state (s1) is
entered. If the origin state has exited before the timeout was consumed, the timeout is canceled.

You can use the timeouts mechanism (tm()) when the quality of service (QOS) accuracy
requirement conforms with the following timeout accuracy. When a timeout occurs, it is inserted
to the event queue related to the reactive instance. The time on which the timeout is consumed
depends on the actual system state. The timeout occurrence depends on three factors:

1. The timeout request time (T)

2. The tick-timer resolution (R)

The resolution specifies how often the system checks if there are expired timeouts.

3. Timeout latency (L)

The tick timer implementation for some operating system adapters is synchronous
(using a call to sleep(interval)). This means that there is a built-in latency (the
time spent processing the expired timeouts). This latency can be significant when the
timeout is very long (involving many timer ticks).

The following formula determines when a timeout will expire:

[(T+L)-R,(T+L)+R]

746 User Guide

 Transition labels

Note: If you use triggered operations and events (including timeouts) in the same
statechart and the triggered operation can be called from an object running in a
thread other than the event consumption thread, it might lead to a race
situation. To prevent the race, make the triggered operations guarded (which
will also prevent the race with timeouts).

Null transitions
In some cases, it is useful to use a transition to leave a state without using a trigger. These are
examples of such cases:

When a state tries to allocate a resource that might not be available

When you want to branch according to some entry action
When you have a join transition
You can accomplish this with a null transition. A null transition is any transition without a trigger
(event or timeout). Null transitions can have guards (for example, [x == 5]). The run-to-
completion semantics of the Rational Rhapsody framework checks for an infinite (run-time) loop
of null transitions, which might otherwise be difficult to detect.

You can modify the maxNullSteps number and recompile the framework if you need to change
the number.

Guards
A guard is a conditional expression that is evaluated based on object attributes and event data.
Rational Rhapsody does not interpret guards. They are host-language expressions, or simply code
chunks, that must resolve to either a Boolean or an integer value that can be tested. Otherwise, the
statechart code generated for guards will not compile.

The following example shows a transition label that consists of a guard and an action that uses the
GEN macro to generate an event:
[x > 7]/controller->GEN(A7Failures)
A transition can consist of only a guard. The low-to-high transition of the condition (or Boolean
value) is considered to be the triggering event. For example, the following guard is a valid
transition label:
[x > 7]

Rational Rhapsody 747

Statecharts

During animation, all guards without triggers are tested every time an event happens. The
following statechart uses several guards without transitions.

This statechart is for the keypad of a home alarm system. When the keypad of the alarm system is
in the idle state, you can enter a code to arm the alarm before leaving the house. After entering the
code, you press the On button to turn the alarm on. Pressing the On button issues an evKeyOn
event. Each time this event occurs, the state machine evaluates the two guards that come after the
decision node, [IS_IN(correct)] or [IS_IN(notEntered)], and follows the path of the one that
evaluates to true.

By using an animated sequence diagram, you can see when a guard is tested. If you want to test a
condition more frequently or at a more regular interval than whenever an event occurs, you can
create a polling mechanism. To do this, create a short timeout transition from the state to itself so
the guard is evaluated on at least these occasions. Alternatively, you can poll using another object
and replace the guard in the current statechart with an event signaled from the polling object.

Note
Using guards that cause side-effects is not typical, because it might cause problems in the
application.

748 User Guide

 Transition labels

Actions
An action expression is a sequence of statements. Like guards, actions are uninterpreted code
chunks based on object attributes and event data.

There is no need to add a semicolon to the last statement; Rational Rhapsody adds one for you.
Therefore, there is no need for any semicolon if there is only one statement.

The following example shows a transition label consisting of a trigger and an action sequence with
more than one step:
e1/x=1;y=2 // comments are allowed
Action expressions must be syntactically legal in the programming language. This means they
must be written within the context of the owner class (the one that owns the statechart being
described). Therefore, all identifiers must be one of the following items:

Class (or superclass) attributes or operations

Role names
Global variables known to the class
Any other identifier will cause failures at compile time.

Actions can reference the parameters of an event or operation as defined by the transition context,
using the pseudo-variable params->. See also Message parameters.

Rational Rhapsody 749

Statecharts

Initial connectors
An initial connector leads into the state (or substate of an Or state, or component of an And state)
that should be entered by default. Each Or state must designate one of its substates as the default
for that state. The default state is indicated using an initial connector, of which there can be only
one per Or state. The initial connector target should be a substate of the Or state to which it
belongs.

The initial connector cannot have a trigger or a guard, although it can have an action. It might
connect to a decision node following which there might be guards.

Each state can have the following properties:

Entry action where an expression executed upon entrance to the state (uninterpreted by
Rational Rhapsody). Note that an uninterpreted expression is resolved by the compiler,
not by the tool.
Exit action where an expression executed upon exit from the state (uninterpreted by
Rational Rhapsody).
Static reactions where actions performed inside a state in response to a triggering event/
operation. The reaction can be guarded by a condition. A static reaction does not change
the active state configuration.

The state executes static reactions if:

– The state is part of the active configuration.
– The trigger and guard are satisfied.
– A lower-level state has not already responded to the trigger.
– There is no active transition that causes the state to be exited.
Default entry
History

Note

When a state contains an entry action, exit action, or static reaction, an icon displays in
the top-right corner of the state. This icon can be used to toggle the display of these actions
in the state.

750 User Guide

 Events and operations

Events and operations

Events inherit from the OMEvent abstract class defined in the Rational Rhapsody framework. They
are abstract entities that do not exist in C++ or other object-oriented programming languages. They
are framework-based, and you can implement them in various ways.

In Rational Rhapsody, both events and messages create operations for a class. You can edit the
operations created as a result of messages, but you cannot modify any event handlers.

Events and operations relate statecharts to the rest of the model by triggering transitions.
Operations specified by a statechart are called triggered operations (as opposed to operations
specified in OMDs, called primitive operations).

Events facilitate asynchronous collaborations and operations facilitate synchronous collaborations.

Triggered operations have a return type and reply. Triggered operations have a higher priority than
events.

In the rest of this guide, the term message means either an event or an operation.

Statecharts can react to operations and events that are part of the interface of a reactive class.
Using a message as a trigger in a statechart to transition from state S1 to state S2 means that if the
object is in S1 when it receives the message, it transitions to S2.

Events that do not trigger an active transition are ignored and discarded. If the object happens to be
in state S3 when it receives the message and S3 does not reference the message, it ignores the
message.

See Events for more information.

Rational Rhapsody 751

Statecharts

Sending events across address spaces

Rational Rhapsody allows you to send events to reactive instances in different address spaces.

This feature applies to multiple address spaces on the same computer. It is not possible to send
events to reactive instances on a different computer.

This feature can be used with the following target environments:

INTEGRITY5
VxWorks6.2diab_RTP
VxWorks6.2gnu_RTP

Note
Currently, the multiple address space feature applies only to Rational Rhapsody in C.
Use of this feature requires:

Setting a number of properties

Calling a different function than that used for sending events within the same address
space

Properties for sending events across address spaces

To allow use of the multiple address space feature, different code generation settings are required.
These settings are controlled by the following property:

C_CG::Configuration::MultipleAddressSpaces
When this boolean property is set to Checked, Rational Rhapsody uses the code
generation settings required for use of the multiple address space feature. The default
value of this property is Cleared, so you must change the value to enable this feature.
In order to be able to receive events from other address spaces, the reactive object must publish the
name by which it will be identified. The following two properties, set at the class level, are used
for this purpose:

C_CG::Class::PublishedName
This is the name that will be used to identify the reactive object in order to send a
distributed event to it.
If there is only one reactive instance of the class, the value of this property is used to
identify the object.
If there is more than one reactive instance of the class, each named explicitly, the name
used to identify the reactive object will be the name that you have given to the object, and
not the property value.
In the case of multiplicity, where the objects are not named explicitly, the name used to

752 User Guide

 Sending events across address spaces

identify the reactive object will be the published name + the index of the object, for
example, if the value of the property PublishedName is truck, then the objects would be
identified by truck[0], truck[1]...
C_CG::Class::PublishInstance
This boolean property indicates whether or not the object should be published as a
reactive instance that is capable of receiving distributed events.
In addition, the following property, which is set at the configuration level, allows you to specify a
specific target address space when sending events, as described in API for sending events across
address spaces:

C_CG::Configuration::AddressSpaceName
When you want to send an event to a reactive object in a specific address space, you
specify the address space by using the value of this property as a prefix, using the format
addressSpaceName::publishedNameOfReactiveObject. The default value of this
property is the name of the relevant component.
If the events to be sent across address spaces have no arguments or only primitive types as
arguments, such as integers or chars, it is sufficient to just set the above properties. However, if the
events to be sent include objects as arguments, you must also set the following properties at the
event level:

C_CG::Event::SerializationFunction
Name of user-provided serialization function to use
C_CG::Event::UnserializationFunction
Name of user-provided unserialization function to use
For details regarding the required structure for these two user-provided functions, see Functions for
serialization/unserialization.

API for sending events across address spaces

When sending events to reactive objects in different address spaces, the function
RidSendRemoteEvent must be used (and not the standard event generation macro RiCGEN):
RiCBoolean RidSendRemoteEvent (const RhpString strReactiveName, struct
RiCEvent* const ev, const RhpPositive eventSize);
strReactiveName - the published name of the destination reactive object

ev - pointer to the event to send

eventSize - the size of the event to send

Note
When providing the strReactiveName parameter for the function
RidSendRemoteEvent, you can indicate which address space contains the target object,

Rational Rhapsody 753

Statecharts

using the format addressSpaceName::publishedNameOfReactiveObject. This allows

you to have objects with the same name in multiple address spaces and still have the event
sent to the appropriate object.
When using this option, the name you use for the address space is the value of the property
C_CG::Configuration::AddressSpaceName, described in Properties for sending events
across address spaces.

For convenience, Rational Rhapsody includes a macro named RiCGENREMOTE, which calls the
function RidSendRemoteEvent:

RiCGENREMOTE ([string - the published name of the destination reactive object], [type of event
with parameters in parentheses])

For example:
RiCGENREMOTE(“destinationObject”, Fstarted());

Functions for serialization/unserialization

If the events to be sent across address spaces have no arguments or only primitive types as
arguments, such as integers or chars, you just have to call the function RiDSendRemoteEvent.
However, if the events to be sent include objects as arguments, you must also provide two
functions - one for serializing and one for unserializing the event arguments:

Serialization function
RhpAddress evStartSerialize(struct RiCEvent_t* const ev, const RhpAddress
buffer, RhpPositive bufferSize, RhpPositive* resultBufferSize);
return value - pointer to the serialized event

ev - pointer of the event to be serialized

buffer - a local buffer that can be used for storing the serialized event (the user can allocate
their own buffer instead)

bufferSize - the size in bytes of the parameter buffer

resultBufferSize - pointer for storing the size of the returned serialized event

Unserialization function
RiCEvent_t* evStartUnserialize(RhpAddress const serializedBuffer, RhpPositive
serializedBufferSize);
return value - pointer to the unserialized event

serializedBuffer - pointer to the serialized buffer

754 User Guide

 Sending events across address spaces

serializedBufferSize - the size of the parameter serializedBuffer

Example of serialization/unserialization functions

The example refers to the event evStart, which is defined as follows:
struct evStart {
RiCEvent ric_event;
/*** User explicit entries ***/
char* msg;
};

RhpAddress evStartSerialize(struct RiCEvent* const ev, const RhpAddress

buffer, RhpPositive bufferSize, RhpPositive* resultBufferSize)
{

evStart* castedEv = (evStart*)ev;

RhpPositive msgLength = strlen(castedEv->msg);
/* Testing the size of the message parameter against the size of local
buffer */
if (bufferSize <= msgLength)
{
/* buffer too small - serialization is aborted */
return NULL;
}
/* copy the message string + the null terminating */
memcpy(buffer, castedEv->msg, msgLength + 1);
*resultBufferSize = msgLength + 1;
return buffer;
}

The function below uses a local buffer called receivedBuffer to store the string of the event
evStart which was passed as a parameter.
RiCEvent* evStartUnserialize(RhpAddress const serializedBuffer,
RhpPositive serializedBufferSize) {
/* copy the message to a local buffer */
memcpy(receivedBuffer, serializedBuffer, serializedBufferSize);
return (RiCEvent*)RiC_Create_evStart(receivedBuffer);
}

Rational Rhapsody 755

Statecharts

Send action elements

The Send Action button can be used in statecharts, activity diagrams, and flow charts to
represent the sending events to external entities.

The Send Action element can be used to specify the following actions:

Event to send
Event target
Values for event arguments
This is a language-independent element, which is translated into the relevant implementation
language during code generation.

Note
Code can be generated for Send Action elements in C, C++, and Java.

Defining send action elements

To define the element, provide the following information in the Features window:

Using the Target list, select the object that is to receive the event.
Using the Event list, select the event that should be sent.
Provide values for the event arguments by selecting the argument in the argument list and
clicking the Value column.

Note
In cases where there are a number of objects based on the same class, you need to provide
additional information after selecting the target from the list. For cases of simple
multiplicity, you must provide the array index to specify the object that receives the event.
In the case of qualified associations, you need to provide the qualifier value for the object
that is to receive the event.
The Preview text box displays the text that is displayed on the element if you select full notation as
the display option to use.

The target list includes all objects known to the class for the statechart. You can choose the name
of the target object, or the name of a port on the target object.

You can click the button next to the Target list to open the Features window of the relationship
with the target object. Similarly, you can click the button next to the Event list to open the Features
window for the selected event.

756 User Guide

 Send action elements

Display options for send actions

The display options for the Send Action element allow you to display a full notation, such as
“Reset (false) to p1” or a short notation, such as “Reset.” Full notation includes the event name,
the values for the event arguments, and the name of the target. Short notation includes only the
event name.

Graphical behavior of send actions

In terms of its behavior in the graphic editors, Send Action elements are connected to states in the
statechart with transitions.

While the graphical behavior of Send Action elements is similar to that of states, it should be
remembered that semantically these elements are not states. For example, you cannot put a
condition on the transition out of a Send Action element (it is an automatic transition).

Code generation for send actions

Code can be generated for Send Action elements in C, C++, and Java.

For each language, code generation for this element is determined by the following properties

CG::Framework::EventGenerationPattern - general format

CG::Framework::EventToPortGenerationPattern - used when sending event to a port

Note
Rational Rhapsody does not support roundtripping for Send Action elements.

Rational Rhapsody 757

Statecharts

And lines
An And line is a dotted line that separates the orthogonal components of an And state. There can
be two or more orthogonal components in a given And state and each behaves independently of the
others. If the system is in an And state, it is also simultaneously in a substate of each orthogonal
component.

The following figure shows an And line.

Drawing And lines

To draw an And line to divide a state into substates:

1. Click the And line button in the Diagram Tools.

2. Click in the middle of the upper edge of the state to anchor the start of the And line.
3. Move the cursor down to the bottom edge of the state and click to anchor the end of the
And line. Rational Rhapsody draws a dotted line that divides the state into two halves
(orthogonal states), as shown in the following figure.

Note that the state label, which used to be inside the state, has moved outside into a tab-like
rectangle.

758 User Guide

 Connectors

Connectors
Rational Rhapsody supports the following connectors:

Decision nodes

History connectors

Merge nodes

Diagram connectors

Termination connectors

EnterExit points
Rational Rhapsody includes connector information for diagram, condition, and EnterExit points in
its repository (core). This means that:

Semantic checks are done by the standard core functions.

Statechart inheritance is core-oriented, not graphics-oriented.
Code is generated for these connectors.
The Undo operation supports all connector actions.
Rational Rhapsody EnterExit points are now UML-compliant.
Reports include information on diagram connectors, decision nodes, and EnterExit points.
Diagram connectors, decision nodes, and EnterExit points are displayed in the browser, as
shown in the following figure.

Rational Rhapsody 759

Statecharts

Decision nodes
Decision Nodes split a single segment into several branches. Branches are labeled with guards that
determine which branch is active.

The following figure shows a decision node.

The following rules apply to decision nodes and branches:

Branches cannot contain triggers.

You can nest branching segments. This means that a branching segment can enter another
decision node.
A decision node can have only one entering transition.
The branching tree should not have cycles.

Else branches
A guard called [else] is active if all the guards on the other branches are false. Each decision
node can have only one else branch.

The semantics of an else branch are similar to a structured if-then-else statement.

760 User Guide

 Connectors

History connectors
History connectors store the most recent active configuration of a state and its substates. Once an
object is created, it is associated with a configuration for an active state, starting in the initial
configuration, and evolving as the statechart responds to messages.

The following figure shows a history connector.

When a transition is attached to a history connector and that transition is triggered, the state
containing the history connector recalls its last active configuration. A state can have a single
history connector.

Transitions from a history connector are constrained to a destination on the same level as the
history connector.

Note
Do not put more than one history connector in a state. Rational Rhapsody allows you to
draw more than one history connector in a state; however, the code generator does not
support this.
A state might have a history property used for recalling the recent active configuration of the state
and its substates. Transitioning into a history connector associated with the state recalls the last
active configuration.

A transition originating from the history connector designates the history default state. The default
history state is taken if no history existed prior to the history enter.

Rational Rhapsody 761

Statecharts

Merge nodes
A merge node combines several segments into one outgoing segment, as shown in the following
figure.

This means that segments share the same line and a common transition suffix. The segments end
up sharing the same transition line.

Diagram connectors
A diagram connector functions similarly to a merge node in that it joins several segments in the
same statechart. Diagram connectors enable you to jump to different parts of a diagram without
drawing spaghetti transitions. This helps avoid cluttering the statechart. The jump is defined by
matching names on the source and target diagram connectors.

Note
You can rename diagram connectors, and the checks are performed during code generation.
Diagram connectors should either have input transitions or a single outgoing transition. A
statechart can have at most one target diagram connector of each label, but it can have several
source diagram connectors with the same label.

During code generation, Rational Rhapsody flattens all junctions and diagram connectors by
merging the common suffix to each segment entering the connector.

In both diagram and merge nodes, a label that belongs to an incoming segment is shared and
duplicated during code generation among outgoing segments of that connector. Rational Rhapsody
merges the guards (conjunction), then concatenates the actions.

762 User Guide

 Connectors

Note
Both incoming and outgoing transitions cannot have labels. If you label the incoming
transitions, do not label the outgoing transition because its label will override the label of
the incoming transition and negate any action or trigger associated with the incoming
transition.
Diagram connectors connect different sections of the same statechart, whereas EnterExit points
connect different statecharts. See EnterExit points.

Termination connectors
The termination connector is the suicide or self-destruct connector. If a transition to a termination
connector is taken, the instance deletes itself. A termination connector cannot have an outgoing
transition.

EnterExit points
EnterExit points are used to represent the entry to / exit from sub-statecharts.

At the level of the parent state, these points represent entry to / exit from the various contained
substates without revealing any information about the specific substate that the transition connects
to.

At the level of the sub-statechart, these points represent the entries to / exits from the parent state
vis-a-vis the other elements in the statechart.

When you create a sub-statechart from a parent that contains deep transitions (that is, transitions
entering one of the substates), EnterExit points are automatically created on the borders of the
parent state in both the sub-statechart and the original statechart.

Once the sub-statechart has been created, you can add additional deep transitions as follows:

1. Add an EnterExit point to the parent state.

2. Add a corresponding EnterExit point in the sub-statechart (manually or using the Update
feature - see Updating EnterExit points).

3. Draw a transition from the EnterExit point to the relevant substate.

Rational Rhapsody 763

Statecharts

Updating EnterExit points

If you would like to add additional EnterExit points after creating a sub-statechart, you can add
them manually to both the parent state in the original statechart and the parent state in the
sub-statechart.

Alternatively, you can have Rational Rhapsody automatically update the EnterExit points:

1. Add one or more EnterExit points to the parent state in either the original statechart or the
sub-statechart.

2. Go to the second statechart, right-click and select Update EnterExit Points.

764 User Guide

 Submachines

Submachines
Submachines enable you to manage the complexity of large statecharts by decomposition. The
original statechart is called the parent, whereas the decomposed part is called the submachine.

Creating a submachine
You can create a submachine from a complex state using either the Edit menu or the menu for the
state.

To create a submachine. on a statechart, right-click a state and then select Create Sub-Statechart.
Rational Rhapsody creates a submachine called <class>.<state>, which is a new statechart
consisting of the submachine state and its contents.

If you decompose the doorClosed state into a submachine, Rational Rhapsody creates a new
submachine.

Actions and reactions move into the top state of the submachine if the transition goes to the
submachine state, and inside the submachine if the transition goes into the nested part.

Note
You cannot create submachines of inherited states. The workaround is to add a dummy state
as a child of the inherited state and make that the submachine state.

Opening a submachine or parent statechart

To open a submachine, right-click the submachine state in the parent statechart and select Open
Sub-Statechart.

Similarly, to open a parent statechart from a submachine, right-click the top state and select Open
Parent Statechart.

Deep transitions
A deep transition is a cross-chart transition, for example, from a parent statechart into a
submachine, or vice versa. When you create a submachine, deep transitions are automatically split
via substates.

Consider the following example:

Rational Rhapsody 765

Statecharts

This statechart has a deep transition that crosses the edge of a parent state (running) and leads into
a nested state (on).

If you make a submachine of the running state, the deep transition is automatically split via
matching EnterExit points created in the parent statechart and submachine, as shown in this
example.

Merging a sub-statechart into its parent statechart

To merge the contents of a sub-statechart into its parent statechart:

1. Select the parent state in the original statechart.

2. Right-click the state and select Merge Back Sub-Statechart.

766 User Guide

 Statechart semantics

Statechart semantics
The following sections describe the object-oriented interpretation of statecharts.

Single message run-to-completion processing

Rational Rhapsody assumes that statecharts react to a single message applied by some external
actor to the statechart. The external actor can be either the system event queue or another object.

Message processing by a statechart is partitioned into steps. In each step, a message is dispatched
to the statechart for processing.

Once a message is dispatched, it might enable transitions triggered by the message. Each
orthogonal component can fire one transition at most as a result of the message dispatch.
Conflicting transitions will not fire in the same step.

The order in which selected transitions fire is not defined. It is based on an arbitrary traversal that
is not explicitly defined by the statechart.

Each component can execute one transition as a result of the message. Once all components
complete executing the transition, the message is said to be consumed, and the step terminates.

After reacting to a message, the statechart might reach a state configuration in which some of the
states have outgoing, active null transitions (transient configurations). In this case, further steps
need to be taken until the statechart reaches a stable state configuration (no more transitions are
active). Null transitions are triggered by null events, which are dispatched to the statechart
whenever a transient-configuration is encountered. Null events are dispatched in a series of steps
until a stable configuration is reached. Once a stable configuration is reached, the reaction to the
message is completed, control returns to the dispatcher, and new messages can be dispatched.

Note
Theoretically, it is possible that the statechart will never reach a stable configuration. The
practical solution is to set a limit to the maximum number of steps allowed for a statechart
to reach a stable configuration. In the current implementation, reaching the maximum
number of steps is treated as if the message processing has been completed.

Rational Rhapsody 767

Statecharts

Active transitions
A transition is active if:

The trigger matches the message posted to the statechart. (Null triggers match the null
event.)
There is a path from the source to the target states where all the guards are satisfied
(evaluate to true).

Note
Guards are evaluated before invoking any action related to the transition.
Because guards are not interpreted, their evaluation might include expressions that cause side
effects. Avoid creating guards that might cause side effects. Guard evaluation strategy is
intentionally undefined as to when guards are evaluated and in which order.

Transition selection
Transition selection specifies which subset of active transitions should fire. Two factors are
considered:

Conflicts
Priorities

Conflicts
Two transitions are said to conflict if both cause the same state to exit. Only orthogonal or
independent transitions fire simultaneously. This means that interleaved execution causes
equivalent results. Disjoint exit states are a satisfactory condition for equivalent results.

Note: With regard to conflicts, static reactions are treated as transitions that exit and
enter the state on which they are defined.

Priorities
Priorities resolve some, but not all, transition conflicts. Rational Rhapsody uses state hierarchies
to define priorities among conflicting transitions. However, lower-level (nested) states can
override behaviors, thus implying higher priority.

The priority for a transition is based on its source state. Priorities are assigned to join transitions
based on their lower source state.

For example, if transition t1 has a source state of s1 and transition t2 has a source state of s2,:

If state s1 is a descendant of state s2, t1 has a higher priority than t2.

768 User Guide

 Statechart semantics

If states s1 and s2 are not hierarchically related, relative priorities between t1 and t2 are
undefined.
Rational Rhapsody does not define a priority with regard to events and transitions other than
arrival order. If two transitions within the same orthogonal component are both active (ready to
fire), as can happen with non-orthogonal guards, only one of them will actually fire, but statecharts
do not specify which one it will be.

Transition selection algorithm

The set of transitions to fire satisfies the following conditions:

All transitions must be active.

Any transition without conflicts will fire.
If a priority is defined between transitions, the transitions with lower priority will not fire.
In any set of conflicting transitions, one transition is selected to fire. In cases where
conflicts are not resolved by priorities, the selected transition is arbitrary.
The above definition of the selection set is not imperative, but implementing a selection algorithm
is done by a straightforward traversal of the active state configuration.

Active states are traversed bottom-up where transitions related to each are evaluated. This
traversal guarantees that the priority principle is not violated. The only issue is resolving transition
conflicts across orthogonal states. This is solved by “locking” each And state once a transition is
fired inside one of its components. The bottom-up traversal and the And state locking together
guarantee a proper selection set.

Rational Rhapsody 769

Statecharts

Transition execution
Once a transition is active and selected to fire, there is an implied action sequencing:

States are exited and their exit actions are executed, where deeper states are exited before
their parent states. In case of orthogonal components, the order among orthogonal siblings
is undetermined.
Actions sequencing follow the direction of the transition. The closer the action to the
source state, the earlier it is evaluated.
Target states are entered and their entry actions are executed, where parent states are
entered before substates. In the case of orthogonal components, the entry order is
undetermined.

Active classes without statecharts

Normally, active classes (threads) must also be reactive (have statecharts). However, you might
have tasks that have no state memory. The workaround of defining a dummy (empty) statechart is
not entirely acceptable because such an active object uses statechart behavior to process events. It
is, however, possible to achieve the same effect by setting the class to active, defining an empty
statechart, then overriding the default behavior by defining an operation named takeEvent() for
the class and adding the wanted behavior to this operation. This method allows you to benefit from
visual debugging, using the event queue, and so on.

Single-action statecharts
Rational Rhapsody cannot interpret simple statecharts that execute a single action and then
terminate. For example, if you represent a task as an active class with a simple statechart that
essentially executes a single action and terminates, you might be tempted to draw your statechart,
as shown in this example.

In this diagram, doIt() represents the action that needs to be spawned.

770 User Guide

 Inherited statecharts

This statechart has two problems:

The Rational Rhapsody framework does not allow an active instance to terminate on the
initial run-to-completion (RTC) step. In other words, the startBehavior() call cannot
end with a destroyed object.
The startBehavior() call executes the initial step on the creator thread, not as part of the
instance thread. The instance thread processes events following the initial step. In this
statechart, the doIt() operation is executed on the creator thread, which is probably not
what was expected.
The workaround is to create a dummy action on the initial connector that leads into a transition.
This action can run on the instance thread and thus terminate normally.

For example, the following statechart postpones the execution of the action until the thread is
ready to process it.

Inherited statecharts
Statechart inheritance begins when a class derives from a superclass that has a statechart. The
statechart of the subclass, the inherited statechart, is initially a clone of that of the superclass. With
the exception of the items listed below, you can add things to an inherited statechart to override
behavior in the inherited class.

You cannot make the following changes to items in the statechart of a subclass:

Change the source of a transition.

Change the triggers (events or triggered operations).
Delete or rename a state.
Draw a state around an existing state.
You can make the following changes to items in the statechart of a subclass:

Rational Rhapsody 771

Statecharts

Change anything that does not affect the model, such as moving things in the diagram
without actually editing.
Add objects to a state.
Add more states, but not re-parent states.
Attach a transition to a different target.
An inherited statechart consists of all the items inherited from the superclass, as well as modified
and added elements.

Note
It is possible to inherit statecharts across packages.
If you edit a base statechart, the derived statechart is redrawn only on demand at checks, code
generation, report generation, or the opening of a derived statechart.

Types of inheritance
Each item in the derived statechart can be:

Inherited where any modifications to an item in the superclass is applied to the item in the
subclass.
Overridden where any modifications to an item in the superclass do not apply to the
subclass. However, deleting an item from the superclass also deletes the item from the
subclass. This is different from C++, for example, where deleting an overridden behavior
in the superclass causes the overridden behavior to become a regular item.
Regular where regular items are owned by the subclass. The item is not related to the
superclass and is not affected by the superclass.
Noting the status of items as inherited, overridden, or regular is crucial both for Rational Rhapsody
and the user.

Note
The current implementation of statechart inheritance is restricted to single inheritance. A
reactive class can have at most one reactive superclass.

Inheritance color coding

Inheritance status is indicated by the following color coding:

Inherited items are gray.

Regular and overridden items are colored in the usual drawing colors.

772 User Guide

 Inherited statecharts

Inheritance rules
Classes with inherited statecharts can reside in different packages. A class with a statechart
(reactive class) can inherit from a class without a statechart. Multiple inheritance of reactive
classes (with statecharts) is not supported. Derived classes can inherit from multiple primitive
classes. Rearranging inheritance hierarchies of reactive classes is not supported.

There are different inheritance rules for states, transitions, triggers, guards, and actions.

Rules for states

The structure of a state in a subclass should be a refinement of the same state of the superclass.
Because of this, state inheritance is strict. All states and their hierarchy are inherited by the
statechart of the subclass.

You can add states to the derived statechart, as long as they do not violate the hierarchy in the
statechart of the superclass. In practice, this means that a regular state cannot contain inherited
substates.

In the following example, the leaf state s2 was refined and became an Or state. The states s1 and
s2 on the right are the inherited states.

You can add And lines to inherited states (adding components). If you convert an inherited Or state
into an And state, the Or state becomes an And state, and one of the components contains its
substates. This is an exception to the previous rule, where the state hierarchy is modified by
introducing an orthogonal component. The component that re-parents the substates is designated
as “main.” In the following example, s2 becomes an And state. The component containing s3 and
s4 is the main component. The name of a component is the same as the name for the And state.

Rational Rhapsody 773

Statecharts

Note the following actions:

You cannot rename inherited states in the derived statechart.

You cannot delete inherited states from a derived statechart.
A state is either inherited or regular. It cannot be overridden.
You cannot change state topology by re-parenting.

Rules for transition labels

You can modify the labels of derived segments according to the following rules:

You cannot modify triggers. They are inherited from the superclass.
You can modify actions and guards.
You can override a guard, but still get changes on the action.
Modifications to the label of the corresponding segment in the superclass no longer affect the
subclass.

Note
The inheritance color coding of the label and the segment are independent. The label can be
overridden while the segment is still inherited, and vice versa.

Rules for entry and exit actions

Both entry and exit actions can be overridden by an inherited state. Once they have been modified
(modifying the text of the action) by a derived state, they reach an overridden state.

Rules for static reactions

Static reactions can be overridden by a derived statechart. Static reactions are designated by their
triggers, which cannot be modified in a derived statechart. Therefore, only the guard and action
can be modified. A static reaction cannot be deleted by a subclass.

Currently, there is no inheritance color coding for static reactions. In addition, tracing inherited
actions between the superclass and the derived statechart is done implicitly by Rational Rhapsody
and is not visible.

774 User Guide

 Inherited statecharts

Rules for connectors

Connectors are always inherited. You cannot modify them or delete them. The following example
illustrates statechart inheritance.

As shown, a basic blower has only On and Off modes.

In a dual-speed blower, the On state is refined to include Fast and Slow modes, as shown in the
following figure.

Rational Rhapsody 775

Statecharts

If you make the On state into an And state, you can add a heat mode, as shown.

Overriding inheritance rules

To override the inheritance rules of statecharts, right-click in the statechart and select Override
Inheritance.

Once you have overridden inheritance, the derived statechart becomes independent from its parent
and you can modify it without constraint. In addition, colors are no longer gray. They are the usual
statechart colors.

To undo the inheritance override, right-click in the statechart and select Unoverride Inheritance.

776 User Guide

 Inherited statecharts

Overriding textual information

The Features window for textual information in statecharts (state entry and exit actions, and guards
and actions for transitions and static reactions) include the Overridden check box. By enabling or
disabling this check box, you can easily override and unoverride statechart inheritance without
actually changing the model. As you toggle the check box on and off, you can view the inherited
information in each of the window fields, and can decide whether to apply the information or
revert back to the currently overridden information.

To apply the change, click OK. The transition changes to

doServe(params->rounds) and it is displayed in blue text instead of gray because it is no
longer overridden.

Note that if you override the textual information, the display colors and statechart change as
follows:

If you unoverride the textual information of a transition or state, the label color reverts to
gray.
If you unoverride a transition target, the transition color reverts to gray and the graphics
are synchronized to the new target.

Rational Rhapsody 777

Statecharts

Refining the hierarchy of reactive classes

You can refine the hierarchy of reactive classes without using overrides and unoverrides (without
losing any information).

For example, suppose you have class C inheriting from class A, as shown in the following OMD.

Suppose you want to change the hierarchy so C inherits from B, which in turn inherits from A.
Therefore:

The statechart that C inherited from A will now be inherited from B; B will inherit its
statechart from A.
The inheritance between A and C will be deleted.
C will not lose any information, because its inherited elements will reference new GUIds.
To make these changes:

1. Using either the browser or the Diagram Tools, create inheritance between B and A.

2. Create inheritance between C and B.

3. Rational Rhapsody displays a window that informs you that you are adding a level of
inheritance, and asks you to confirm the deletion of the inheritance between C and A. Click
Yes.

778 User Guide

 Inherited statecharts

The following figure shows the revised OMD.

Rational Rhapsody 779

Statecharts

Removing a level of inheritance

Suppose you now want C to inherit from A instead of B, thereby removing a level of inheritance.
When you draw the inheritance between C and A, Rational Rhapsody notifies you that a level of
inheritance will be removed and asks for confirmation.

Click Yes. The following figure shows the revised OMD.

Inheritance between two reactive classes

If you try to establish inheritance between two distinct reactive classes (for example, B inherits
from A), Rational Rhapsody displays a message stating that the action will result in overriding
statechart inheritance. Click Yes to override the statechart inheritance.

780 User Guide

 IS_IN Query

IS_IN Query
The Rational Rhapsody framework provides the query function IS_IN(state), which returns a
true value if the state is in the current active configuration.

Note the following information:

IS_IN(state) returns true if the state is in the active configuration at the beginning of the
step. For states entered in a step, IS_IN(state) returns false, unless the states are being
re-entered.
The state name passed to IS_IN() is the implementation name, which might be different
from the state name if it is not unique.
For example, the following state names are generated for the statechart shown in the
figure:
State* B; State* B_A2; State* B_A1;
State* A; State* A2; State* A1;

The implementation name of A1 in state A is simply A1 because it was drawn first. The
implementation name of A1 in state B is B_A1, because it is a duplicate.

Rational Rhapsody 781

Statecharts

In the following statechart, the transition to substate A4 in state A is taken only if the object is still
in substate A1 in A after one second. The transition to substate A4 in state B is taken only if the
object is still in substate A1 in B after two seconds.

In these two cases, the IS_IN() query requires the use of the implementation names A1 and B_A1
to differentiate between like-named substates of two different states.

The IS_IN macro is called as if it were a member operation of a class. If you want to test the state
of another class (for example, a relation), you must use the relation name. For example, if you have
a relation to a class A called itsA and you want to see if A is in the idle state, you would use itsA-
>IS_IN(idle) rather than A->IS_IN(idle).

782 User Guide

 Message parameters

Message parameters
Message data are formal parameters used within the transition context. By default, if the message
is an event, the names of message parameters are the same as the arguments (data members) of the
event class.

You reference event arguments in a statechart using the pseudo-variable params-> with the
following syntax:
event/params->event_arg1, params->event_arg2
Consider a class Firecracker that processes an event discharge, which has an argument color.
The argument color is of an enumerated type Colors, with the possible values red (0), green (1),
or blue (2). In the statechart, you would indicate that you want to pass a color to the event when it
occurs using the following label on the transition:
discharge/params->color
When you run the application with animation, you can generate a discharge event and pass it the
value red by typing the following command in the animation command field:
Firecracker[0]->GEN(discharge(red))
The application understands red as a value being passed to the argument color of event
discharge because of the notation params->color. The color red is translated to its integer value
(0), and the event is entered on the event queue of the main thread as follows:
Firecracker[0]->discharge((int)color = 0)
Finally, the event queue processes the event discharge with the value red passed via params->.
The Firecracker explodes in red and transitions from the ready to the discharged state.

The way the params-> mechanism works is as follows: When you create an event and give it
arguments, Rational Rhapsody generates an event class (derived from OMEvent) with the
arguments as its attributes. Code for events is generated in the package file.

Rational Rhapsody 783

Statecharts

The following sample code shows the event discharge, which has one argument called color.
The code was generated in the header file for the Default package:

//-------------------------------------------------------
// Default.h
//-------------------------------------------------------
class discharge;
class Firecracker;
enum Colors {red, green, blue};
class discharge : public OMEvent {
DECLARE_META_EVENT
//// User explicit entries ////
public :
Colors color;
//// User implicit entries ////
public :
// Constructors and destructors:
discharge();
//// Framework entries ////
public :
discharge(Colors p_color);
// This constructor is need in code instrumentation
discharge(int p_color);
};
When the Firecracker event queue is ready to take the event discharge, it calls
SETPARAMS(discharge). SETPARAMS is a macro defined in oxf\state.h as follows:

#define SETPARAMS(type) type *params; params=(type*)event

Calling SETPARAMS(discharge) allocates a variable params of type pointer to an event of type
discharge. This enables you to use params->color in the action part of the transition as a short-
hand notation for discharge->color.

784 User Guide

 Modeling of continuous time behavior

Modeling of continuous time behavior

There are three types of behaviors typical of embedded systems:

Simple means implemented in functions and operations

Continuous means expressed by items such as PID control loops or digital filters
Reactive means state-based behavior
Although the Rational Rhapsody GUI directly supports only simple and reactive behaviors, you
can implement all three types. To address the continuous time aspects, you can reference or
include any code you are currently using to express continuous behavior in any of the operations
defined within Rational Rhapsody.

This means that if you are defining your continuous behavior elements manually, you can continue
to do so. If you are using another tool to define your continuous behavior and that tool generates
code, you can include that code.

Interrupt handlers
The ability to add an interrupt handler depends on operating system support. Typically, a static
function without parameters is added by passing its address to an operating system operation like
InstallIntHdlr (operating system-dependent). The static function can be either a special
singleton object or a function defined within a package. This operation must use compiler-specific
utilities to get to the registers. Eventually, it must return and execute a return from the interrupt
instruction.

You can pass the data from the interrupt handler to the CPU (assuming that the interrupt handler
needs to), in the following ways:

Generate an event (using the GEN() macro), which then goes via the operating system to
the reactive object (which should be in a different thread).
Use a rendezvous object with a read/write toggle lock. The interrupt handler checks
whether the lock is in the write state, then updates the data and puts the lock in the read
state. The reader (in another thread) periodically checks the lock and only reads when it is
in the read state. If it is in that state, the reader reads the data and updates the lock to its
write state. This can easily be extended to a queue structure.
Write the interrupt handler manually outside Rational Rhapsody and send it to the
operating system message queue for the target thread. Typically, if the operating system
does not support interrupt handlers directly, you store the current handler in your function
and write the address of the function in the appropriate place in the interrupt vector table.
When the interrupt goes off, either the new function replaces the old interrupt handler
(meaning when it is done it simply returns) or it chains to it (calls the original). In any

Rational Rhapsody 785

Statecharts

event, when the interrupt handler is decommissioned, you replace the vector in the vector
table with the original address.

Inlining of statechart code

Consider the following statechart:

When you implement this statechart using the flat scheme, you should expect the following
methods to be added to the class and called through a series of a few function calls from
rootState_dispatchEvent():

int MyClass::s2TakeNull() {
int res = eventNotConsumed;
s2_exit();
//#[ transition 2
f2();
f2();
//#]
s3_entDef();
res = eventConsumed;
return res;
};
int MyClass::s1TakeNull() {
int res = eventNotConsumed;
s1_exit();
//#[ transition 1
f1();
f1();
//#]
s2_entDef();
res = eventConsumed;
return res;
};
In fact, what happens is that the transition code (between the //#[ and //#] brackets) is
immediately inlined (embedded) inside rootState_dispatchEvent(), as follows:
int MyClass::rootState_dispatchEvent(short id) {
int res = eventNotConsumed;
switch(rootState_active) {
case s1:
{
if(id == Null_id)
{
popNullConfig();

786 User Guide

 Tabular statecharts

//#[ transition 1
f1();
f1();
//#]
pushNullConfig();
rootState_subState = s2;
rootState_active = s2;
res = eventConsumed;
}
break;
};
case s2:
{
if(id == Null_id)
{
popNullConfig();
//#[ transition 2
f2();
f2();
//#]
rootState_subState = s3;
rootState_active = s3;
res = eventConsumed;
}
break;
};
};
return res;
};
This code is more efficient because it saves a few function calls via inlining of code. Inlining is
available using the CG::Class::ComplexityForInlining property of the class, which is set to 3
by default. This means that if the user code (the action part of the transition) is shorter than three
lines, it is inlined (or embedded) where the function call used to be instead of the function call. To
get the “expected” result (not inlined), set this property to 0.

Tabular statecharts
In addition to viewing statecharts as diagrams, it is possible to view statecharts in a tabular format.
You can also make certain types of changes to your statechart when using the tabular view.

The property StatechartDiagram::StateDiagram::DefaultView can be used to determine the

default view for statecharts - diagram view or tabular view. This property can be set at the level of
individual statecharts or higher.

Format of statechart tables

When Rational Rhapsody displays a statechart as a table:

The rows of the table represent the various states.

The columns of the table represent the triggers that lead to transitions between states.

Rational Rhapsody 787

Statecharts

Table cells display the new state the application will enter when the relevant trigger
occurs.
The table contains a column named Null which is used for transitions not associated with a
specific trigger.
For an And state, each of the substates is listed in its own row, nested below the And state.
Diagram connectors do not appear in the table. Rather, the resulting transition between
states is shown.
The following statechart elements appear as rows in the table: condition connectors,
history connectors, junction connectors, join bars and fork bars.
Enter/Exit points appear as rows in the table, nested under their owner state.
Default connectors (transitions) are depicted as outgoing transitions from a state called
ROOT.

Modifying statecharts from tabular view

You can make the following types of changes to statecharts when using the tabular view:

Add transitions
Add events
Delete transitions
Delete events
Delete states

Adding a transition
To add a new transition to the table:

Select the name of the target state and drag it to the table cell where the row of the source state
intersects the column of the relevant trigger.

To add a transition not associated with a specific trigger:

Select the name of the target state and drag it to the table cell where the row of the source state
intersects the NULL column.

To add a default connector (transition) for the statechart:

Select the name of the target state and drag it to the table cell where the ROOT row intersects the
Initial column.

788 User Guide

 Tabular statecharts

Adding an event
To add an event when in tabular view, click the Add model element button on the toolbar. The
Add new element window will be displayed, allowing you to create one or more new events.

Deleting a transition, event, or state

To delete a transition, event, or state:

1. Select the relevant transition cell, event header, or row name in the table.

2. Open the context menu and select Delete from Model.

Note
You cannot delete the ROOT state.

Menu for tabular view

When in tabular view, the menu includes an option of switching to diagram view (and vise versa).

Refreshing the contents of the statechart table

If you use the browser to add/remove elements, click the Refresh button in the toolbar to refresh
the contents of the statechart table

Locating model elements

If the tabular view is set as the default view for a statechart, then when you try locating a model
element included in the statechart, Rational Rhapsody will highlight the relevant cell in the
statechart table.

Rational Rhapsody 789

Statecharts

790 User Guide

 Panel diagrams

A panel diagram provides you with a number of graphical control elements that you can use to
create a graphical user interface (GUI) to monitor and regulate an application. Each control
element can be bound to a model element (attribute/event/state). During animation, you can use the
animated panel diagram to monitor (read) and regulate (change values/send events) your user
application. For more information about animation, see Animation.

This feature provides a convenient way to demonstrate the design and, additionally, provides you
with an easy way to create a debug interface for the design.

Note
The panel diagram feature is only available for Rational Rhapsody in C and Rational
Rhapsody in C++.
You can use a panel diagram to create the following types of panels for design and testing
purposes:

Hardware control panel designed for operating and monitoring machinery or instruments.
Software graphical user interface (GUI) for display on a computer screen allowing the
computer application user easier access to the application function than would be required
if the user entered commands or other direct operational techniques.

Rational Rhapsody 791

Panel diagrams

Panel diagram features

You can create a panel diagram to design a graphical interface in Rational Rhapsody in C and
Rational Rhapsody C++ projects. Developers can use the diagrams to:

Simulate and prototype a panel

Imitate hardware devices for users
Activate and monitor a user application
Test applications by triggering events and change attributes values

Note
Panel diagrams are intended only for simulating and prototyping, and not for use as a
production interface for the user application. In addition, panel diagrams can only be “used”
on the host and can be “used” only from within Rational Rhapsody.

792 User Guide

 Panel diagram features

The following illustration shows an animated panel diagram for a hypothetical coffee maker
application. During animation, the developer of the application can test it by doing such things as,
for example:

Turn on the coffee maker application by clicking the power On/Off Switch control.
Use the coffeeContainer and milkContainer Bubble Knob controls to increase/decrease
the amount of coffee and milk that is available.
Order a coffee by clicking the evCoin Push Button control. The following could happen:
– Messages appear on the Matrix Display control, such as Filling Coffee or
Filling Cup.
– The coffeeContainer and milkContainer Level Indicator controls go down
as these items are dispensed.
– The cup Level Indicator control rises as coffee fills a cup, until the Please
Take Your Cup message displays on the Matrix Display control.
– The Take cup LED control turns red.
– The cupCounter Digital Display control keeps a count of each cup of coffee
made.
Indicate that a cup of coffee has been taken by clicking the evTakeCup Push Button
control, which could reset the coffee machine.

Rational Rhapsody 793

Panel diagrams

Creating a panel diagram

The following procedure lists the general steps to create and use a panel diagram. References to
more specific procedures are noted when necessary.

1. Open your Rational Rhapsody model with model elements ready for use.

2. Create a panel diagram. Choose Tools > Diagrams > Panel Diagram.
For basic information on diagrams, including how to create, open, and delete them, see
Graphic editors.

3. Create a control element in your panel diagram; click any of the tools on the panel
diagram Diagram Tools. See Panel diagram drawing tools.
4. Bind the control to a model element; right-click a control and select Features. Use the
Element Binding tab on the Control Properties tab. See Bind a control element to a model
element.

5. Make whatever changes you might want for the control; see:

Change the settings for a control element

Change the properties for a control element, when applicable

Setting the value bindings for a button array control, when applicable
Changing the display name for a control element
6. Set your model for animation. See Animation.

7. Generate and make your model. Run your application and the animation for the panel
diagram. When animation starts, the control on your panel diagram is initiated with its
bound model element value. See Basic code generation concepts.
8. Use your control elements on the animated panel diagram. Note that when animation is
running, the Control Properties window and the Display Options window are unavailable.

9. Terminate animation to terminate the use of the control element and exit animation.

10. Use ReporterPLUS to produce a panel diagram report. For more information, see
ReporterPLUS.

794 User Guide

 Create panel diagram elements

Create panel diagram elements

The following sections describe the drawing tools available for a panel diagram. For basic
information on diagrams, including how to create, open, and delete them, see Graphic editors.

Panel diagram drawing tools

The Diagram Tools for a panel diagram contains the following tools.

Drawing
Description
Icon
Select Lets you select a control on a panel diagram.

Knob Represents a Bubble Knob control. See Drawing a bubble knob control.

Gauge Represents a Gauge control. See Drawing a gauge control.

Meter Represents a Meter control. See Drawing a meter control.

Level Indicator Represents a Level Indicator control. See Drawing a level indicator control.

Matrix Display Represents Matrix Display control that shows a text string. See Drawing a matrix
display control.
Digital Display Represents a Digital Display control that shows numbers. See Drawing a digital
display control.

LED Represents a light-emitting diode control. See Drawing an LED control.

On/Off Represents an On/Off Switch control. See Drawing an on/off switch control.

Push Button Represents a Push Button control. See Drawing a push button control.

Button Array Represents a Button Array control. See Drawing a button array control.

Text Box Represents an editable Text Box control. See Drawing a text box control.

Slider Represents a Slider control. See Drawing a slider control.

Rational Rhapsody 795

Panel diagrams

Drawing a bubble knob control

The Bubble Knob control is an input/output control, as shown in the following figure in its default
non-animated appearance:

Note the following information:

You can bind (map) it to an attribute.

Its attribute type is a Number.
By default its control direction is set to In/Out, though you can change it to In or Out.
To draw a Bubble Knob control on a panel diagram:

1. Click the Knob button in the Diagram Tools.

2. Click the drawing area to create a Bubble Knob control, or click and drag so that you can
create the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.
4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a bubble knob control
To change the display name for the control, see Changing the display name for a
control element

796 User Guide

 Create panel diagram elements

Drawing a gauge control

The Gauge control is an output control that displays as an analog round dial, as shown in the
following figure in its default non-animated appearance:

Note the following information:

You can bind it to an attribute.

Its attribute type is a Number.
To draw a Gauge control on a panel diagram:

1. Click the Gauge button in the Diagram Tools.

2. Click the drawing area to create a Gauge control, or click and drag so that you can create
the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.
4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a gauge control
To change the display name for the control, see Changing the display name for a
control element

Rational Rhapsody 797

Panel diagrams

Drawing a meter control

The Meter control is an output control that displays as an analog meter, as shown in the following
figure in its default non-animated appearance:

Note the following information:

You can bind it to an attribute.

Its attribute type is a Number.
To draw a Meter control on a panel diagram:

1. Click the Meter button in the Diagram Tools.

2. Click the drawing area to create a Meter control, or click and drag so that you can create
the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.
4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a meter control
To change the display name for the control, see Changing the display name for a
control element

798 User Guide

 Create panel diagram elements

Drawing a level indicator control

The Level Indicator control is an output control. By default it displays as a vertical 3-dimensional
cylindrical level indicator, as shown in the following figure in its default non-animated
appearance. However, you can change its appearance (for example to a 3-dimensional square
shape) through the Properties tab of the Control Properties window.

Note the following information:

You can bind it to an attribute.

Its attribute type is a Number.
To draw a Level Indicator control on a panel diagram:

1. Click the Level Indicator button in the Diagram Tools.

2. Click the drawing area to create a Level Indicator control, or click and drag so that you can
create the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a level indicator control
To change the display name for the control, see Changing the display name for a
control element

Rational Rhapsody 799

Panel diagrams

Drawing a matrix display control

The Matrix Display control is an output control, as shown in the following figure in an example of
an animated appearance:

Note the following information:

You can bind it to an attribute.

Its attribute types are Number and String.
To draw a Matrix Display control on a panel diagram:

1. Click the Matrix Display button in the Diagram Tools.

2. Click the drawing area to create a Matrix Display control, or click and drag so that you can
create the control to a certain size.
3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a matrix display control
To change the display name for the control, see Changing the display name for a
control element

800 User Guide

 Create panel diagram elements

Drawing a digital display control

The Digital Display control is an output control, as shown in the following figure in an example of
an animated appearance:

Note the following information:

You can bind it to an attribute.

Its attribute types are a Number and a String.
To draw a Digital Display control on a panel diagram:

1. Click the Digital Display button in the Diagram Tools.

2. Click the drawing area to create a Digital Display control, or click and drag so that you can
create the control to a certain size.
3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a digital display control
To change the display name for the control, see Changing the display name for a
control element

Rational Rhapsody 801

Panel diagrams

Drawing an LED control

The LED control is an output control, as shown in the following figure in an example of an
animated appearance:

Note the following information:

You can bind it to a state or an attribute.

Its attribute type is a Boolean.
To draw an LED control:

1. Click the LED button in the Diagram Tools.

2. Click the drawing area to create a LED control.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.
4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a LED control
To change the display name for the control, see Changing the display name for a
control element

802 User Guide

 Create panel diagram elements

Drawing an on/off switch control

The On/Off Switch control is an input/output control, as shown in the following figure in one of it
many possible shape styles in an example of an animated appearance:

Note the following information:

You can bind it to a state or an attribute.

Its attribute type is a Boolean.
By default its control direction is set to In/Out, though you can change it to In or Out.
To draw an On/Off Switch control on a panel diagram:

1. Click the On/Off Switch button in the Diagram Tools.

2. Click the drawing area to create a On/Off Switch control.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a on/off switch control
To change the display name for the control, see Changing the display name for a
control element

Rational Rhapsody 803

Panel diagrams

Drawing a push button control

The Push Button control is an input control, as shown in the following figure in its default
non-animated appearance:

Note the following information:

You can bind it to an event.

By default, this control injects a none parameter event.
You can set a fix parameter for the event.
To draw a Push Button control on a panel diagram:

1. Click the Push Button button in the Diagram Tools.

2. Click the drawing area to create a Push Button control, or click and drag so that you can
create the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the display name for the control, see Changing the display name for a
control element

804 User Guide

 Create panel diagram elements

Drawing a button array control

The Button Array control is an input/output control, as shown in the following figure in its default
non-animated appearance:

Note the following information:

You can bind it to an attribute. In addition, you can set a value for each switch to be set on
the attribute.
Its attribute types are a Number and a String.
By default its control direction In/Out, though you can change it to In or Out.
To draw a Button Array control on a panel diagram:

1. Click the Button Array button in the Diagram Tools.

2. Click the drawing area to create a Button Array control, or click and drag so that you can
create the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the value binding for the control; see Setting the value bindings for a
button array control.
To change the display name for the control, see Changing the display name for a
control element

Rational Rhapsody 805

Panel diagrams

Drawing a text box control

The editable Text Box control is an input/output control, as shown in the following figure in its
default non-animated appearance:

Note the following information:

You can bind it to an attribute.

Its attributes types are a Number and a String.
By default its control direction In/Out, though you can change it to In or Out.
To draw a Text Box control on a panel diagram:

1. Click the Text Box button in the Diagram Tools.

2. Click the drawing area to create a Text Box control, or click and drag so that you can
create the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the display name for the control and/or its data flow direction, see
Changing the display name for a control element.
To change the format settings (for example, line, fill, and font) for a Text Box
control, see Change the format of a single element.

806 User Guide

 Create panel diagram elements

Drawing a slider control

The Slider control is an input/output control, as shown in the following figure in its default
non-animated appearance:

Note the following information:

You can bind it to an attribute.

Its attribute type is a Number.
By default its control direction In/Out, though you can change it to In or Out.
To draw a Slider control on a panel diagram:

1. Click the Slider button in the Diagram Tools.

2. Click the drawing area to create a Slider control, or click and drag so that you can create
the control to a certain size.

3. To bind the control element to the model element that the control is to regulate or monitor,
see Bind a control element to a model element.

4. Make whatever changes you might want for the control:

To change the settings for the control, see Change the settings for a control element
To change the properties for the control, see Change the properties for a control
element and Properties for a slider control
To change the display name for the control, see Changing the display name for a
control element

Rational Rhapsody 807

Panel diagrams

Bind a control element to a model element

In a panel diagram, the control element is a GUI that has to be connected to some “real” source/
target element. In Rational Rhapsody, binding (mapping) ties the operation between the control
element to the model element it is to regulate or monitor.

A binding definition for a control element defines the following binding settings of each control
element.

Element type:
– Control element - input sets data to bound element
– Monitor element - output gets data from bound element
Valid model elements for binding (attribute, event, and state)
Value attribute types that can be set/get by the control element (Number, String, or
Boolean)
A binding definition for a control element is predefined in Rational Rhapsody. It cannot be
changed. For example, the Bubble Knob has the following binding definition:

Element role: input, output, or both

Valid model elements: attributes
Value types: numbers
Be sure that the bounded element type (for example, an int) is being supported by the control.

In the binding operation, you have to set the model element for binding. You can also set the
instance path.

808 User Guide

 Bind a control element to a model element

Binding a control element

To bind a control element to a model element in a panel diagram:

1. Right-click the control and select Features to open the Control Properties window.

2. On the Element Binding tab, depending on your situation:

If the control has no binding, the Control Binding Browser opens with the project
container as the selected item. Use the browser to navigate to and select the
elements for which you want to bind to the control element, or you can enter the
element path in the Instance Path box.

Note that the browser root is the project and the end nodes are the meta classes
that can be bound for the particular control element. If no relevant end node is
found, the system notifies you that no relevant item was found and the Control
Properties window does not open.
If the control has a bound element, the browser opens with the bound model
element selected.
If no relevant element for binding is found in the model, the Element Binding tab
displays blank with a note to that effect.

For more information about binding, see More about binding a control element.
3. Click OK.

More about binding a control element

Note the following about binding a control element:

Binding an item of a modeled root Instance

In the case where the element for binding is owned by a modeled root Instance, the object
is displayed by the browser on the Element Binding tab on the Control Properties
window containing all relevant items for binding. You can select the element from the
browser or alternatively type in the element path (stating at modeled root object) in the
Instance Path box.
Binding an item of a dynamic root Instance

In the case where the element for binding is owned by a dynamic root Instance (modeled
class that will be instantiated at run time), the element root class is displayed by the
browser on the Element Binding tab containing all relevant items for binding. You can
select the element from the browser or alternatively type in the element path (stating at
modeled root class) in the Instance Path box.

Rational Rhapsody 809

Panel diagrams

In both ways, if the dynamic Instance name is different from the default class instance
name, the name should be entered following item selection.
Binding an item with multiplicity on its root object and parts

In the case where bound element owner parts has multiplicity: Selecting the element
through the browser on the Element Binding tab creates the path in the Instance Path
box with “0” multiplicity on the relevant parts. You can then set the multiplicity as
needed. If you enter a path, it is your responsibility to add multiplicity where needed.
The following table summarizes the binding (mapping) characteristics for each panel diagram
control element:

Attribute types
Only attributes that hold predefined primitive (or enumeration) types could be bound. The
supported predefined types are:

Number: int, unsigned int, short, unsigned short, long, double, float,
RhpInteger, RhpPositive, RhpReal
String: char, char*, RhpString, OMString, CString
Boolean: Bool, OMBoolean, RhpBoolean, RiCBoolean

810 User Guide

 Change the settings for a control element

Change the settings for a control element

You can change the settings for the control elements available for a panel diagram. For example,
when applicable, its:

Minimum and maximum values

Shape style (in the case of a On/Off switch)
Caption (in the case of the Push Button control)
Color scheme (in the case of the Matrix Display and Digital Display controls
You do this through the Settings tab on the Control Properties window for a control element.

Where possible (for example, for the Bubble Knob control), you can also change their control
direction (to input, output, or both). By default, they are set to InOut. You can use the Control
Direction area of the Settings tab on the Control Properties window to change the control
direction when possible.

Changing the settings for a control

To change the settings for a control:

1. Right-click a control and select Features to open the Control Properties window.

2. Make your changes on the Settings tab. Note that the settings that are available depend on
the type of control element you have selected.

3. If applicable for a control, select an radio button in the Control Direction area:

In for input flow

Out for output flow
InOut for input/output flow
4. Click OK.

Rational Rhapsody 811

Panel diagrams

Change the properties for a control element

You can change the properties for many of the control elements available for a panel diagram (for
example, its background color, range values, caption, and so on). You can make changes through
the Properties tab of the Control Properties window for a control. These properties are ActiveX
controls.

Note: The Properties tab displays only when appropriate for the selected control
element. In addition, the tab shows only those settings that are applicable to
that control element.

Properties for a bubble knob control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for a Bubble Knob control. You can change the properties as follows:

Device Settings Explanation

BackgroundColor To change the background color for the control, click the drop-down arrow
in the right column and select a color from the Palette tab that displays.
DivisionLIneThickness To change the thickness of the major division lines (also referred to tick
markers), change the value in the right column. The default value is 2.
DotColor To change the color for the dot (indicator mark) on the Bubble Knob control,
click the drop-down arrow in the right column and select a color from the
Palette tab that displays.
EndAngle To change the distance around the dial (between the minimum and
maximum values), change the value in the right column. The default value
is -45.
Font To change the font for the text (for example, the numbers) on the control,
click the Ellipses button in the right column and select a font from the Font
window that displays. The default value is Arial.
GradientFactor To change the gradient factor for the control, change the value in the right
column. The higher the number the more pronounced the gradient for the
appearance of the knob, which displays as light to dark. The default value
is 0.7.
LineColor To change the color of all the tick markers, click the drop-down arrow in the
right column and select a color from the Palette tab that displays.
MaximumValue To change the maximum value for the control, change the value in the right
column. The default value is 100.
MinimumValue To change the minimum value for the control, change the value in the right
column. The default value is 0.

812 User Guide

 Change the properties for a control element

Device Settings Explanation

NumberOfDivisions To change the number of major division lines (tick markers) for the control,
change the value in the right column. The default value is 10.
For example, with the maximum value set at 100, minimum value at 0, and
division value at 5, your Bubble Knob control would show major tick
markers at 0, 20, 40, 60, 80, and 100.
NumberOfSubdivisions To change the number of minor division lines (tick markers) between two
major ones, change the value in the right column. The default value is 1,
which means no minor tick marker displays between two major tick
markers. For example, to make three subdivision areas appear between
two major markers, enter a value of 3.
RelativeBubbleRadius To change the relative bubble radius for the control, change the value in the
right column. This regulates the relative size of the Bubble Knob control,
which includes its number scale. The default value is 0.6.
RelativeDotPositionRadius To change the placement (closer or farther away) of the dot indicator
relative to the 0 value marker, change the value in the right column. The
default value is 0.75.
RelativeDotRadius To change the size of the dot indicator, change the value in the right
column. The default value is 0.11.
RelativeExternalRadius To change the relative external radius for the control, change the value in
the right column. This setting changes the length of the major and minor
tick markers while still touching the control. The default value is 1.1.
RelativeInternalRadius To change the relative internal radius for the control, change the value in
the right column. This setting changes the length of the major and minor
tick markers and how far away they are from the the bubble. The default
value is 1.
RelativeTextRadius To change the relative text radius for the control, change the value in the
right column. This setting changes the distance between the scale numbers
and their associate tick makers. The default value is 0.98.
StartAngle To change the position of the minimum value marker and the dot indicator,
change the value in the right column. The default value is 225.
SubdivisionLineThickness To change the thickness of the minor division lines (tick markers), change
the value in the right column. The default value is 1.
TextColor To change the color for the text (scale numbers) on the control, click the
drop-down arrow in the right column and select a color from the Palette tab
that displays.
Value To change the default placement of the dot indicator, change the value in
the right column. The default value is 0.
ValueFormatString To change the value format of the numbers on the control, change the
value in the right column. The default value is %.0f, which shows
numbers, for example, as 0, 10, 20, and so on. For the value %.1f, the
control would show number as 0.0, 10.0, 20.0, and so on.

Rational Rhapsody 813

Panel diagrams

Properties for a gauge control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for a Gauge control. You can change the properties as follows:

Device Settings Explanation

BackColor To change the back color for the control, click the drop-down arrow in
the right column and select a color from the Palette tab that displays.
BackgroundPicture To add/change an image that displays as the background for the
control, click the Ellipses button in the right column and open a bitmap
file.
Caption To insert a caption to show in the center of the Gauge control, type
your text in the right column.
You can use RelativeCaptionY, RelativeCaptionX,
RelativeCenterY, and RelativeCenterX to position the caption
somewhere on the gauge other than its center.
CaptionColor To change the color for your caption text, click the drop-down arrow in
the right column and select a color from the Palette tab that displays.
CaptionFont To change the font for your caption text, click the Ellipses button in the
right column and select a font from the Font window that displays. The
default value is Arial.
DivisionLineThickness To change the thickness of the major division lines (also known as tick
markers), change the value in the right column. The default value is 2.
EnclosingCircleColor To change the background color for the control, click the drop-down
arrow in the right column and select a color from the Palette tab that
displays.
EndAngle To change the angle of the scale on the high end of the control, change
the value in the right column. The value widens (lower value) or shrinks
(higher value) the empty space between the low and high ends of the
control. The default is -45.
ExternalCircleThickness To change the thickness of the external circle of the control, change
the value in the right column. The default value is 3.
ForeColor To change the foreground color, click the drop-down arrow in the right
column and select a color from the Palette tab that displays.
GreenColor To change the color (typically green) of the OK area of the control, click
the drop-down arrow in the right column and select a color from the
Palette tab that displays.
GreenStartValue To change the beginning value for the OK area on the control, change
the value in the right column. The default value is 60.
IndexColor To change the color of the needle indicator for the control, click the
drop-down arrow in the right column and select a color from the Palette
tab that displays.
IndexLineThickness To change the thickness of the needle indicator for the control, change
the value in the right column. The default value is 0.

814 User Guide

 Change the properties for a control element

Device Settings Explanation

InternalCircleThickness To change the thickness of the internal circle of the control, change the
value in the right column. The default value is 2.
MaximumValue To change the maximum value for the control, change the value in the
right column. The default value is 100.
MinimumValue To change the minimum value for the control, change the value in the
right column. The default value is 0.
NumberColor To change the color of the numbers on the control, click the drop-down
arrow in the right column and select a color from the Palette tab that
displays.
NumberFont To change the font for the numbers on the control, click the Ellipses
button in the right column and select a font from the Font window that
displays. The default value is Arial.
NumberOfDivisions To change the number of major division lines (tick markers) for the
control, change the value in the right column. The default value is 10.
For example, with the maximum value set at 100, minimum value at 0,
and division at 5, your control would show major tick markers at 0, 20,
40, 60, 80, and 100.
NumberOfSubdivisions To change the number of minor division lines (tick markers) between
two major ones, change the value in the right column. The default
value is 2, which means one minor tick marker displays between two
major tick markers. For example, to make three subdivision areas
appear between two major markers, enter a value of 3.
RedColor To change the color (typically red) of the Warning area of the control,
click the drop-down arrow in the right column and select a color from
the Palette tab that displays.
RedStartValue To change the beginning value for the Warning area on the gauge,
change the value in the right column. The default value is 90.
RelativeCaptionX To change the relative X coordinate (east/west) of the text entered for
Caption, change the value in the right column. The default value
is 0.5.
RelativeCaptionY To change the relative Y (north/south) coordinate of the text entered for
Caption, change the value in the right column. The default value
is 0.5.
RelativeCenterX To change the relative center Y coordinate of the control, change the
value in the right column. The default value is 0.5.
RelativeCenterY To change the relative center X coordinate of the control, change the
value in the right column. The default value is 0.55.
RelativeEnclosingCircleRadius To change the relative enclosing circle radius of the control, change the
value in the right column. The default value is .98.
RelativeExternalRadius To change the relative external radius of the control, change the value
in the right column. The default value is 1.1.

Rational Rhapsody 815

Panel diagrams

Device Settings Explanation

RelativeIndexBackLength To change the relative length the needle indicator from the back (not
pointy) end, change the value in the right column. The default value
is 0.3.
RelativeIndexLength To change the relative length of the needle indicator from the front
(pointy) end, change the value in the right column. This lengthens the
needle indicator at its back (wider) end. The default value is 1.2.
RelativeInternalRadius To change the relative internal radius of the control, change the value
in the right column. The default value is 0.35.
RelativeTextRadius To change the relative position of the text (scale numbers), change the
value in the right column. The default value is 1.1.
ScaleCircleColor To change the color of the scale circle, click the drop-down arrow in the
right column and select a color from the Palette tab that displays.
StartAngle To change the position of the minimum value marker and the needle
indicator, change the value in the right column. The default value
is 225.
StepValue To change the step value, change the value in the right column. The
default is 1.
SubdivisionLineThickness To change the thickness of the minor division lines (tick markers),
change the value in the right column. The default value is 1.
TailAngle To change the thickness of the needle indicator, change the value in
the right column. The default is 165.
Value To change the default value for the needle indicator, change the value
in the right column. The default value is 0.
ValueFormatString To change the value format of the scale number, change the value in
the right column. The default value is %.0f, which shows numbers, for
example, as 0, 10, 20, and so on. For the value %.1f, the control
would show number as 0.0, 10.0, 20.0, and so on.
YellowColor To change the color (typically yellow) of the Caution area of the control,
click the drop-down arrow in the right column and select a color from
the Palette tab that displays.
YellowStartValue To change the beginning value for the Caution area on the gauge,
change the value in the right column. The default value is 75.

816 User Guide

 Change the properties for a control element

Properties for a meter control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for a Meter control. You can change the properties as follows:

Device Settings Explanation

BackgroundImage To add an image so that it displays as the background for the control,
click the Ellipses button in the right column and open a bitmap file.
BottomCoverColor To change the color of the bottom cover for the control, click the
drop-down arrow in the right column and select a color from the Palette
tab that displays.
You can use this setting in conjunction with
BottomCoverRelativeHeight.
BottomCoverLabelFront To change the font for the text on the bottom cover for the control, click
the Ellipses button in the right column and select a font from the Font
window that displays. The default value is Arial.
You use this setting in conjunction with Caption and
BottomCoverTextColor.
BottomCoverRelativeHeight To change the height of the bottom cover area for the control, change
the value in the right column. The default is 0.2.
You can use this setting in conjunction with BottomCoverColor.
BottomCoverTextColor To change the color for the text that displays in the bottom cover area,
click the drop-down arrow in the right column and select a color from
the Palette tab that displays.
You use this setting in conjunction with Caption and
BottomCoverLabelFront.
Caption To insert a caption to appear in the bottom cover area of the control,
type your text in the right column.
You can use this setting in conjunction with
BottomCoverLabelFront and BottomCoverTextColor.
GreenColor To change the color (typically green) of the OK area of the control, click
the drop-down arrow in the right column and select a color from the
Palette tab that displays.
GreenStartValue To change the beginning value for the OK area on the control, change
the value in the right column. The default value is 60.
IndexColor To change the color of the needle indicator for the control, click the
drop-down arrow in the right column and select a color from the Palette
tab that displays.
IndexThickness To change the thickness of the needle indicator, change the value in
the right column. The default value is 2.
InstrumentBackgroundColor To change the background color for the control, click the drop-down
arrow in the right column and select a color from the Palette tab that
displays.
MaximumValue To change the maximum value for the control, change the value in the
right column. The default value is 100.

Rational Rhapsody 817

Panel diagrams

Device Settings Explanation

MinimumValue To change the minimum value for the control, change the value in the
right column. The default value is 0.
NumberOfDivisions To change the number of major division lines (tick markers) for the
control, change the value in the right column. The default value is 5.
For example, with the maximum value set at 100, minimum value at 0,
and division at 5, your control would show major tick markers at 0, 20,
40, 60, 80, and 100.
NumberOfSubdivisions To change the number of minor division lines (tick markers) between
two major ones, change the value in the right column. The default
value is 1, which means no minor tick marker displays between two
major tick markers. For example, to make three subdivision areas
appear between two major markers, enter a value of 3.
RedColor To change the color (typically red) of the Warning area of the control,
click the drop-down arrow in the right column and select a color from
the Palette tab that displays.
RedStartValue To change the beginning value for the Warning area on the control,
change the value in the right column. The default value is 90.
RelativeIndexLength To change the relative length of the needle indicator, change the value
in the right column. The default value is 1.1.
RelativeTextRadius To change the relative position of the text (scale numbers), change the
value in the right column. The default value is 0.9.
ScaleColor To change the color of the scale outline and numbers, click the
drop-down arrow in the right column and select a color from the Palette
tab that displays.
ScaledCircleRelativeDiameter To change the relative diameter of the control, change the value in the
right column. The default is 1.75.
ScaledCircleRelativeShifting To change the relative height of the control, change the value in the
right column. The default is 0.3.
ScaleRelativeWidth To change the relative wide of the scale, change the value in the right
column. The default is 0.1.
ScaleThickLineWidth To change the top and bottom lines of the scale, change the value in
the right column. The default is 2.
ScaleThinLineWidth To change the thickness of the vertical lines of the scale, change the
value in the right column. The default is 1.
ShadedAreaRelativeSize The default is 0.
SmallScaleFont To change the font for the scale numbers, click the Ellipses button in
the right column and select a font from the Font window that displays.
The default value is Arial.
StepValue To change the step value, change the value in the right column. The
default is 1.
Value To change the default value for the needle indicator, change the value
in the right column. The default value is 0.

818 User Guide

 Change the properties for a control element

Device Settings Explanation

ValueFormatString To change the value format of the scale number, change the value in
the right column. The default value is %.1f, which shows numbers, for
example, as 0.0, 10.0, 20.0, and so on. For the value %.0f, the control
would show number as 0, 10, 20, and so on.
VisibleScaleRelativeSize To change the relative size of the visible scale, change the value in the
right column. The default value is 1.2.
YellowColor To change the color (typically yellow) of the Caution area of the control,
click the drop-down arrow in the right column and select a color from
the Palette tab that displays.
YellowStartValue To change the beginning value for the Caution area on the control,
change the value in the right column. The default value is 75.

Rational Rhapsody 819

Panel diagrams

Properties for a level indicator control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for a Level Indicator control. You can change the properties as follows:

Device Settings Explanation

BackColor To change the background color for the control, click the drop-down arrow
in the right column and select a color from the Palette tab that displays.
CurrentValue To change the current (default) value for the control, change the value in
the right column. The default is 20.
DrawTextLabels The default is True.
EnableThreshold1 To enable/disable the appearance of the top middle threshold level line,
change the value in the right column. True enables the appearance;
False disables it.
The default is True.
EnableThreshold2 To enable/disable the appearance of the bottom middle threshold level line,
change the value in the right column. True enables the appearance;
False disables it.
The default is True.
Font To change the font for the numbers on the control, click the Ellipses button
in the right column and select a font from the Font window that displays.
The default value is Arial.
FormatString To change the value format of the scale numbers, change the value in the
right column. The default value is %.0f, which shows numbers, for
example, as 0, 10, 20, and so on. For the value %.1f, the control would
show number as 0.0, 10.0, 20.0, and so on.
GradientFactor To change the gradient factor for the control, change the value in the right
column. The higher the number the more pronounced the gradient for the
appearance of the knob, which displays as light to dark. The default value
is 0.7.
HorizontalLayout To change the layout of the level indicator to be horizontal, change the
value in the right column to True. The default is False.
LiquidColor To change the color of the level indicator, click the drop-down arrow in the
right column and select a color from the Palette tab that displays.
MaximumValue To change the maximum value for the control, change the value in the right
column. The default value is 100.
MinimumValue To change the minimum value for the control, change the value in the right
column. The default value is 0.
NumberOfDivisions To change the number of major division lines (tick markers) for the control,
change the value in the right column. The default value is 5.
For example, with the maximum value set at 100, minimum value at 0, and
division at 5, your control would show major tick markers at 0, 20, 40, 60,
80, and 100.

820 User Guide

 Change the properties for a control element

Device Settings Explanation

NumberOfSubdivisions To change the number of minor division lines (tick markers) between two
major ones, change the value in the right column. The default value is 1,
which means no minor tick marker displays between two major tick
markers. For example, to make three subdivision areas appear between
two major markers, enter a value of 3.
RelativeDepth To change the appearance of the relative depth of the control, change the
value in the right column. The default is 0.2.
For example, a value of 0 gives the control a flat tall rectangular
appearance. While a value of 0.2 gives it a 3-dimensional cylindrical
appearance.
Note that the appearance of the level indicator control is also affected by
SquareShape, RelativeHeight and RelativeWidth.
Note also that the appearance of the orientation of the level indicator is
affected by HorizontalLayout.
RelativeHeight To change the relative height of the control, change the value in the right
column. The default is 0.9.
RelativeWidth To change the relative width of the control, change the value in the right
column. The default is 0.9.
ShadedAreaRelativeSize The default is 0.
SquareShape To change the appearance of the Level Indicator control to look like a 3-
dimensional square, change the value in the right column to True. The
default is False.
Threshold1Color To change the color of the top middle threshold level line, click the
drop-down arrow in the right column and select a color from the Palette tab
that displays.
Threshold1Thickness To change the thickness of the top middle threshold level line, change the
value in the right column. The default is 1.
Threshold1Value To change the position of the bottom middle threshold level line, change the
value in the right column. The default is 75.
Threshold2Color To change the color of the bottom middle threshold level line, click the
drop-down arrow in the right column and select a color from the Palette tab
that displays.
Threshold2Thickness To change the thickness of the bottom middle threshold level line, change
the value in the right column. The default is 1.
Threshold2Value To change the position of the bottom threshold level line, change the value
in the right column. The default is 35.
UseColorGradients The default is True.

Rational Rhapsody 821

Panel diagrams

Properties for a matrix display control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for a Matrix Display control. You can change the properties as follows:

Device Settings Explanation

BackColor To change the background color for the control, click the drop-down arrow
in the right column and select a color from the Palette tab that displays.
Caption To insert a caption to appear on the control, type your text in the right
column.
Style To change the appearance of the background of the control, change the
value in the right column. The default is 0.

Properties for a digital display control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for a Digital Display control. You can change the properties as follows:

Device Settings Explanation

BackColor To change the background color for the control, click the drop-down arrow
in the right column and select a color from the Palette tab that displays.
DisplayedString To insert text to display on the control, type your text in the right column.
Style To change the appearance of the background for the control, change the
value in the right column. The default is 4.

822 User Guide

 Change the properties for a control element

Properties for a LED control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for an LED control. You can change the properties as follows:

Device Settings Explanation

BackColor To change the background color for the control, click the drop-down arrow
in the right column and select a color from the Palette tab that displays
BlackWhenOff To change the appearance of the control to black when the application is
off, change the value in the right column to True. The default is False.
Blinking To change it so that the LED is blinking, change the value in the right
column to True. The default is False.
BlinkingTimeMillesec To change the blinking rate, change the value in the right column. The
default is 300.
Color To change the color for the LED, change the value in the right column. The
default is 2.
State To change the state for the LED, change the value in the right column to
True. The default is False.
Style To change the appearance of the background of the control, change the
value in the right column. The default is 0.

Rational Rhapsody 823

Panel diagrams

Properties for a on/off switch control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for an On/Off Switch control. You can change the properties as follows:

Device Settings Explanation

BackColor To change the background color for the control, click the drop-down arrow
in the right column and select a color from the Palette tab that displays.
IconSet To change the appearance of the On/Off switch icon, change the value in
the right column.

0=

1=

2=

3=

4=

5=

6=

7=

8=

9= (default)
State To change the state of the control, change the value in the right column.
The default is True.
UserInteractionEnabled To change is user interaction is enable, change the value in the right
column. The default is True.

824 User Guide

 Change the properties for a control element

Properties for a slider control

The following table lists the properties that appear on the Properties tab of the Control Properties
window for a Slider control. You can change the properties as follows:

Device Settings Explanation

BackgroundColor To change the background color for the control, click the drop-down arrow
in the right column and select a color from the Palette tab that displays.
DivisionLIneThickness To change the thickness of the major division lines (also referred to tick
markers), change the value in the right column. The default value is 2.
DotColor To change the color for the indicator mark on the Slider control, click the
drop-down arrow in the right column and select a color from the Palette tab
that displays.
EndAngle To change the distance on the Slider rule (between the minimum and
maximum values), change the value in the right column. The default value
is -45.
Font To change the font for the text (for example, the numbers) on the control,
click the Ellipses button in the right column and select a font from the Font
window that displays. The default value is Arial.
GradientFactor To change the gradient factor for the control, change the value in the right
column. The higher the number the more pronounced the gradient for the
appearance of the Slider control, which displays as light to dark. The
default value is 0.7.
LineColor To change the color of all the tick markers, click the drop-down arrow in the
right column and select a color from the Palette tab that displays.
MaximumValue To change the maximum value for the control, change the value in the right
column. The default value is 100.
MinimumValue To change the minimum value for the control, change the value in the right