User Guide and

Reference Manual

Version 2.0
January 2009
Scientific Toolworks, Inc.
230 N 1680 E, Ste. OP1
St George, UT 84790

Copyright © 2009 Scientific Toolworks, Inc. All rights reserved.

The information in this document is subject to change without notice.

Scientific Toolworks, Inc., makes no warranty of any kind regarding this
material and assumes no responsibility for any errors that may appear
in this document.

RESTRICTED RIGHTS: Use, duplication, or disclosure by the Govern-

ment is subject to restrictions as set forth in subparagraph (c)(1)(ii) of
the Rights in Technical Data and Computer Software clause at DFAR
252.227-7013 (48 CFR). Contractor/Manufacturer is Scientific Tool-
works, Inc., 230 N 1680 E, Ste. OP1, St. George, UT 84790.

NOTICE: Notwithstanding any other lease or license agreement that

may pertain to or accompany the delivery of this restricted computer
software, the rights of the Government regarding use, reproduction, and
disclosure are as set forth in subparagraph (c)(1) and (2) of Commercial
Computer Software-Restricted Rights clause at FAR 52.227-19.

Part Number: USTAND2-GEN-UG-469 (1/09)

 Contents
Chapter 1 Introduction
What is Understand 2.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2
Licensing Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
Understand 2.0 Editions . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
Understand 2.0 Language Variants . . . . . . . . . . . . . . . . 1–4
For Those Who Don’t Like to Read Manuals . . . . . . . . . . . . . 1–5

Chapter 2 Parts and Terminology

Using Understand 2.0 Windows . . . . . . . . . . . . . . . . . . . . . . . 2–2
Understand 2.0 Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . 2–3
Parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–4
Starting Understand 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–5
Other Ways to Run Understand 2.0 . . . . . . . . . . . . . . . . 2–6
Right-Click Menus Are Everywhere . . . . . . . . . . . . . . . . . . . . 2–7
Quickly Find Things in Your Source . . . . . . . . . . . . . . . . . . . . 2–9
Entity Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–9
Entity Locator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–10
Find in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–11
Favorites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–11
Info Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–12
Source Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–13
Architecture Browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–14
Snapshot Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–15
Graphical Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–16
ASCII and HTML Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–17
Perl and C APIs for Custom Reporting . . . . . . . . . . . . . . . . . 2–18

Chapter 3 Configuring Your Project

About Understand 2.0 Projects . . . . . . . . . . . . . . . . . . . . . . . . 3–2
The Understand 2.0 Project Database . . . . . . . . . . . . . . 3–2
Creating a New Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–3
New Project Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–4
Project Configuration Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 3–8
Languages Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–10
Files Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–11
Adding Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–12
Adding Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–14
Deleting Directories and Files . . . . . . . . . . . . . . . . . . . 3–14

Understand 2.0 User Guide and Reference Manual iii

Contents

Setting Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–14

Scanning Watched Directories . . . . . . . . . . . . . . . . . . . 3–15
Setting File Portability . . . . . . . . . . . . . . . . . . . . . . . . . . 3–16
File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–17
File Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–18
Scheduled Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–19
Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–22
Metrics->Selected Category . . . . . . . . . . . . . . . . . . . . . 3–23
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–24
Reports->Output Category . . . . . . . . . . . . . . . . . . . . . . 3–24
Reports->Options Category . . . . . . . . . . . . . . . . . . . . . 3–25
Reports->Selected Category . . . . . . . . . . . . . . . . . . . . 3–25
Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–26
Ada Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–28
Ada->Macros Category. . . . . . . . . . . . . . . . . . . . . . . . . 3–30
C++ Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–32
C++->Includes Category. . . . . . . . . . . . . . . . . . . . . . . . 3–34
C++->Includes->Auto Category . . . . . . . . . . . . . . . . . . 3–35
C++->Includes-> Ignore Category . . . . . . . . . . . . . . . . 3–36
C++->Includes-> Replacement Text. . . . . . . . . . . . . . . 3–36
C++->Macros Category . . . . . . . . . . . . . . . . . . . . . . . . 3–37
C++->Macros-> Undefines Category . . . . . . . . . . . . . . 3–38
C# Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–39
C#->References Category . . . . . . . . . . . . . . . . . . . . . . 3–39
FORTRAN Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–40
Fortran>Includes Category . . . . . . . . . . . . . . . . . . . . . . 3–42
Other Fortran Categories . . . . . . . . . . . . . . . . . . . . . . . 3–42
Java Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–43
Java->Class Paths Category . . . . . . . . . . . . . . . . . . . . 3–44
JOVIAL Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–45
Jovial->Copy Category . . . . . . . . . . . . . . . . . . . . . . . . . 3–46
Pascal Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–47
Pascal->Macros Category . . . . . . . . . . . . . . . . . . . . . . 3–48
Pascal->Namespaces Category . . . . . . . . . . . . . . . . . . 3–48
Pascal->Standard Library Paths Category . . . . . . . . . . 3–49
Pascal->Search Paths Category . . . . . . . . . . . . . . . . . 3–49
PL/M Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–50
PL/M>Includes Category . . . . . . . . . . . . . . . . . . . . . . . 3–50
Setting General Preferences . . . . . . . . . . . . . . . . . . . . . . . . . 3–51
General Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–52
User Interface Category . . . . . . . . . . . . . . . . . . . . . . . . 3–54
User Interface->Lists Category . . . . . . . . . . . . . . . . . . . 3–55
User Interface-> Alerts Category . . . . . . . . . . . . . . . . . 3–56

iv Understand 2.0 User Guide and Reference Manual

 Contents

Key Bindings Category. . . . . . . . . . . . . . . . . . . . . . . . . 3–57

TrackBack Category. . . . . . . . . . . . . . . . . . . . . . . . . . . 3–58
Analyze Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–59
Configure Category . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–59
Command Window Category . . . . . . . . . . . . . . . . . . . . 3–59
Portability Category . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–60
Editor Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–61
Editor->Advanced Category . . . . . . . . . . . . . . . . . . . . . 3–63
Editor->Styles Category . . . . . . . . . . . . . . . . . . . . . . . . 3–65
Editor->Browse Category . . . . . . . . . . . . . . . . . . . . . . . 3–66
Analyzing the Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–67
Converting an Understand 1.4 Project . . . . . . . . . . . . . . . . . 3–69

Chapter 4 Exploring Your Codebase

PLEASE RIGHT CLICK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–2
Various Windows Explained... . . . . . . . . . . . . . . . . . . . . . . . . 4–3
Project Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–4
Entity Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–5
Using the Filter Field . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–6
Customizing the Display . . . . . . . . . . . . . . . . . . . . . . . . . 4–6
Root Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–7
Info Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–8
Drilling Down A Relationship . . . . . . . . . . . . . . . . . . . . . 4–9
Displaying More or Less Information . . . . . . . . . . . . . . 4–10
Searching the Info Browser . . . . . . . . . . . . . . . . . . . . . 4–10
Syncing the Info Browser . . . . . . . . . . . . . . . . . . . . . . . 4–11
Visiting Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . 4–11
Visiting References . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–12
Viewing Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–12
Saving and Printing Info Browser Text . . . . . . . . . . . . . 4–13
Entity History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–13
Project Browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–14
Exploring a Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–16
Favorites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–17
Creating a Favorite. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–17
Using the Favorites . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–18

Chapter 5 Searching Your Source

Searching: An Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–2
Entity Locator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–3
Resizing Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–3
Long versus Short Names . . . . . . . . . . . . . . . . . . . . . . . 5–3
Column Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–4

Understand 2.0 User Guide and Reference Manual v

Contents

Choosing Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–4

Filtering the List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–5
Find in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–8
Find Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–10
Replace in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–11
Finding Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–14

Chapter 6 Editing Your Source

Source Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–2
Scope List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–3
Status Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–3
Status Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–3
Selecting and Copying Text . . . . . . . . . . . . . . . . . . . . . . 6–4
Browse Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–4
Right-Click Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–5
Saving Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–6
Searching Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7
Incremental Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7
Find. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–8
Source Visiting History . . . . . . . . . . . . . . . . . . . . . . . . . . 6–8
Contextual Information Sidebar . . . . . . . . . . . . . . . . . . . 6–9
Other Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–10
Bracket Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–10
Folding and Hiding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–10
Commenting and Uncommenting . . . . . . . . . . . . . . . . . 6–10
Changing Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–11
Keyboard Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 6–11
Recording and Replaying Macros. . . . . . . . . . . . . . . . . 6–11
Creating and Opening Files . . . . . . . . . . . . . . . . . . . . . 6–11
Bookmarking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–12
Managing Source Editor Tabs . . . . . . . . . . . . . . . . . . . 6–13
Printing Source Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–14

Chapter 7 Architecting Your Codebase

About Architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–2
Using the Architecture Browser. . . . . . . . . . . . . . . . . . . . . . . . 7–3
Exploring Architectures. . . . . . . . . . . . . . . . . . . . . . . . . . 7–3
Generating Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–6
Generating Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–7
Managing Architectures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–9
Creating an Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–10
Creating Predefined Architectures . . . . . . . . . . . . . . . . 7–10
Using the Architecture Wizard . . . . . . . . . . . . . . . . . . . 7–11

vi Understand 2.0 User Guide and Reference Manual

 Contents

Building an Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–13

Using XML to Manage Architectures . . . . . . . . . . . . . . . . . . 7–15
Exporting Architectures to XML . . . . . . . . . . . . . . . . . . 7–15
Importing XML Architectures . . . . . . . . . . . . . . . . . . . . 7–15
Using Architecture Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–16

Chapter 8 Managing Source Changes

About Snapshots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–2
Creating Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–3
Creating Scratch Snapshots. . . . . . . . . . . . . . . . . . . . . . 8–4
Creating Named Snapshots . . . . . . . . . . . . . . . . . . . . . . 8–5
Creating Snapshots from Other Locations . . . . . . . . . . . 8–6
Creating TrackBack Snapshots . . . . . . . . . . . . . . . . . . . 8–9
Managing Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–10
Edit Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–11
Delete Snapshot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–12
Enable/Disable Snapshot . . . . . . . . . . . . . . . . . . . . . . . 8–12
Protect/Unprotect Snapshot . . . . . . . . . . . . . . . . . . . . . 8–13
Purge Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–13
Copy Snapshot Information . . . . . . . . . . . . . . . . . . . . . 8–13
Comparing Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–14
Exploring Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–17
Changed Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–18
Entity Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–22
Patch File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–26
Difference List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–26
Using Change Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–27
Comparing Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–29
Comparing the Same Entity Between Snapshots . . . . 8–29
Comparing Two Entities . . . . . . . . . . . . . . . . . . . . . . . . 8–31
Comparing Files and Folders . . . . . . . . . . . . . . . . . . . . . . . . 8–32
Comparing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–35
Using TrackBack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–36

Chapter 9 Using Graphical Views

Project Overview Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–2
Graphical View Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–4
Hierarchy Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–5
Structure Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–5
General Rules for Using Graphical Browsers. . . . . . . . . 9–6
Filtering Out Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–8
Reuse Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–9
Sync Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–9

Understand 2.0 User Guide and Reference Manual vii

Contents

Types of Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–10

Hierarchy View Types. . . . . . . . . . . . . . . . . . . . . . . . . . 9–10
Hierarchy View Examples. . . . . . . . . . . . . . . . . . . . . . . 9–11
Structure View Types . . . . . . . . . . . . . . . . . . . . . . . . . . 9–14
Structure View Examples . . . . . . . . . . . . . . . . . . . . . . . 9–14
Graphical Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–18
Controlling Graphics Layout . . . . . . . . . . . . . . . . . . . . . . . . . 9–19
Called by Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–20
Constants Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–20
Default Members Menu . . . . . . . . . . . . . . . . . . . . . . . . 9–20
Dependent Of Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–20
Dependent Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–20
Duplicate Subtrees Menu . . . . . . . . . . . . . . . . . . . . . . . 9–20
Extended By Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–20
Extends Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–21
External Functions Menu . . . . . . . . . . . . . . . . . . . . . . . 9–21
Filename Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–21
Function Pointer Menu . . . . . . . . . . . . . . . . . . . . . . . . . 9–21
Globals Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–21
Implements Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–21
Implemented By Menu . . . . . . . . . . . . . . . . . . . . . . . . . 9–21
Imports Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–22
Included By Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–22
Includes Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–22
Inherits Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–22
Inherited By Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–22
Intrinsic Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–22
Invocations Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–23
Layout Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–23
Level Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–24
Locals Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–24
Members Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–25
Name Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–25
Objects Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–25
Operators Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–25
Parameters Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–26
Private Members Menu. . . . . . . . . . . . . . . . . . . . . . . . . 9–26
Protected Members Menu . . . . . . . . . . . . . . . . . . . . . . 9–26
Public Members Menu . . . . . . . . . . . . . . . . . . . . . . . . . 9–26
Renames Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–26
Routines Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–26
Scale Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–27
Sort Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–27
Spacing Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–27
Sql Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–27

viii Understand 2.0 User Guide and Reference Manual

 Contents

Static Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–27

Text Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–28
Types Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–28
Typetext Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–28
Unknown Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–28
Unresolved Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–29
Usedby Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–29
Uses Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–29
Variables Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–29
Withs Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–29
With Bys Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–29
Saving Graphical Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–30
Saving Views to Files . . . . . . . . . . . . . . . . . . . . . . . . . . 9–30
Saving Views as Visio Files . . . . . . . . . . . . . . . . . . . . . 9–30
Printing Graphical Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–32
Graphical View Printing . . . . . . . . . . . . . . . . . . . . . . . . 9–32

Chapter 10 Generating Reports

Configuring Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–2
Generating Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–4
Viewing Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–5
An Overview of Report Categories . . . . . . . . . . . . . . . . . . . . 10–6
Augment with the PERL or C API. . . . . . . . . . . . . . . . . 10–7
Cross-Reference Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–8
Data Dictionary Report . . . . . . . . . . . . . . . . . . . . . . . . . 10–8
Program Unit Cross-Reference Report . . . . . . . . . . . . 10–9
File Contents Report . . . . . . . . . . . . . . . . . . . . . . . . . 10–10
Object Cross-Reference Report . . . . . . . . . . . . . . . . . 10–10
Type Cross-Reference Report . . . . . . . . . . . . . . . . . . 10–11
Class and Interface Cross-Reference . . . . . . . . . . . . 10–11
Macro Cross-Reference . . . . . . . . . . . . . . . . . . . . . . . 10–12
Include File Cross-Reference. . . . . . . . . . . . . . . . . . . 10–12
Exception Cross-Reference Report . . . . . . . . . . . . . . 10–13
Structure Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–14
Declaration Tree. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–14
Class Extend Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–15
Invocation Tree Report. . . . . . . . . . . . . . . . . . . . . . . . 10–16
Simple Invocation Tree Report. . . . . . . . . . . . . . . . . . 10–16
With Tree Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–16
Simple With Tree Report . . . . . . . . . . . . . . . . . . . . . . 10–17
Generic Instantiation Report. . . . . . . . . . . . . . . . . . . . 10–17
Renames Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–17
Import Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–17
Quality Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–18

Understand 2.0 User Guide and Reference Manual ix

Contents

Program Unit Complexity Report . . . . . . . . . . . . . . . . 10–18

FORTRAN Extension Usage Report . . . . . . . . . . . . . 10–19
Implicitly Declared Objects Report . . . . . . . . . . . . . . . 10–20
Uninitialized Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–20
Unused Variables and Parameters. . . . . . . . . . . . . . . 10–21
Unused Objects Report . . . . . . . . . . . . . . . . . . . . . . . 10–21
Unused Types Report. . . . . . . . . . . . . . . . . . . . . . . . . 10–21
Unused Program Units Report . . . . . . . . . . . . . . . . . . 10–22
Withs Not Needed Report. . . . . . . . . . . . . . . . . . . . . . 10–22
Metrics Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–23
Project Metrics Report . . . . . . . . . . . . . . . . . . . . . . . . 10–24
Class Metrics Report . . . . . . . . . . . . . . . . . . . . . . . . . 10–24
Class OO Metrics Report . . . . . . . . . . . . . . . . . . . . . . 10–25
Program Unit Metrics Report . . . . . . . . . . . . . . . . . . . 10–25
File Metrics Report . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–26
File Average Metrics Report . . . . . . . . . . . . . . . . . . . . 10–27

Chapter 11 Generating Metrics

About Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–2
Project Metrics Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–3
Project Metrics Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–4
Exporting Metrics to HTML . . . . . . . . . . . . . . . . . . . . . . . . . . 11–5
Exporting Metrics to a CSV File . . . . . . . . . . . . . . . . . . . . . . 11–6
Browsing Metric Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–8

Chapter 12 Running External Commands

Using an External Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–2
Configuring Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–3
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–5
Adding Tools to the Right-Click Menus . . . . . . . . . . . . . . . . 12–10
Adding Tools to the Tools Menu . . . . . . . . . . . . . . . . . . . . . 12–12
Adding Tools to the Toolbar . . . . . . . . . . . . . . . . . . . . . . . . 12–13
Importing and Exporting Tool Commands. . . . . . . . . . . . . . 12–14
Running External Commands . . . . . . . . . . . . . . . . . . . . . . . 12–15

Chapter 13 Command Line Processing

Using the und Command Line. . . . . . . . . . . . . . . . . . . . . . . . 13–2
Getting Help on Command Line Options . . . . . . . . . . . 13–2
Creating a New Project. . . . . . . . . . . . . . . . . . . . . . . . . 13–3
Creating a Project and Adding Sources in One Step . . 13–3
Adding Files to a Project. . . . . . . . . . . . . . . . . . . . . . . . 13–3
Creating a List of Files . . . . . . . . . . . . . . . . . . . . . . . . . 13–4
Analyzing a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13–4

x Understand 2.0 User Guide and Reference Manual

 Contents

Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . 13–5

Using the understand Command Line . . . . . . . . . . . . . . . . 13–11

Chapter 14 Quick Reference

File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–2
Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–2
Search Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–3
Project Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–3
Metrics Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–4
Architect Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–4
Change Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–5
Tools Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–5
Window Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–6
Help Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–7

Understand 2.0 User Guide and Reference Manual xi

Contents

xii Understand 2.0 User Guide and Reference Manual

Chapter 1 Introduction
This chapter introduces the Understand 2.0 software.
This manual assumes a moderate understanding of the
programming language in which your project is written.

This chapter contains the following sections:

Section Page
What is Understand 2.0? 1–2
Licensing Issues 1–3
For Those Who Don’t Like to Read Manuals 1–5

Understand 2.0 User Guide and Reference Manual 1-1

Chapter 1: Introduction

What is Understand 2.0?

Understand 2.0 is a cross-platform, multi-language, maintenance-
oriented IDE (interactive development environment). It is designed
to help maintain and understand large amounts of legacy or newly
created source code. The source code analyzed may include Ada,
C++, C#, FORTRAN, Java, JOVIAL, Delphi/Pascal, and/or PL/M.
It offers code navigation using a detailed cross-reference, a syntax-
colorizing “smart” editor, and a variety of graphical reverse
engineering views.

Understand 2.0 creates a repository of the relations and structures

contained within the software project. The repository is then used to
learn about the source code.

1-2 Understand 2.0 User Guide and Reference Manual

 Licensing Issues

Understand 2.0 has analysis features that help you quickly answer
questions such as:
• What is this entity?
• Where is it changed?
• Where is it referenced?
• Who depends on it?
• What does it depend on?
Understand 2.0 has architecture features that help you create
hierarchical aggregations of source code units. You can name these
units and manipulate them in various ways to create interesting
hierarchies for analysis.

Licensing Issues
Understand 2.0 is available in several editions and variants. They all
use the same installation; the license code controls the feature set.
....................................................................................................
Understand 2.0 The Understand 2.0 editions have different sets of features related
Editions to metrics, architectures, and snapshots. The editions are:
• Understand 2.0 Engineer
• Understand 2.0 Pro
• Understand 2.0 Analyst
(Understand 2.0 Non-Commercial has all features of Understand 2.0
Analyst, but is available only to non-commercial users.)
This manual identifies features that are only available in certain
editions using icons. If the icon is at the start of a section, it applies
to the entire section. Otherwise, it applies only to the paragraph it is
next to.
• Analyst: This feature is available only if you have the “Analyst”
edition.
• Pro/Analyst: This feature is available if you have the “Pro”
edition or the “Analyst” edition.
• No icon: The feature is available in all editions.
The Understand 2.0 title bar shows which edition you are using. If
you have licenses for more than one edition, you can change the
current edition by choosing Help->Run at License Level and then
restarting Understand 2.0.

Understand 2.0 User Guide and Reference Manual 1-3

Chapter 1: Introduction

....................................................................................................
Understand 2.0 Understand 2.0 supports Ada, C/C++/C#, FORTRAN, Java,
Language Variants JOVIAL, Pascal, and PL/M.
The Engineer edition of Understand 2.0 supports only C/C++, C#,
and Java. The “Analyst” and “Pro” editions of Understand 2.0 come
in two language variants:
• L1: C/C++/C#, Java, Pascal/Delphi, FORTRAN
• L2: C/C++/C#, Java, Pascal/Delphi, FORTRAN, Ada, PL/M,
JOVIAL
This manual describes all languages supported by any variant.
However, this manual does not provide detailed descriptions of how
specific language features are handled.
The following list provides a brief overview of the language versions
and/or compilers supported:
• Ada: Understand 2.0 supports Ada83, Ada95, and Ada05 code,
separately, or in combination.
• C/C++: Understand 2.0 analyzes K&R or ANSI C source code
and most constructs of the C++ language. Understand 2.0 works
with any C compiler, and has been tested with most of the
popular ones. Note that C++ templates are not yet supported.
• C#: Understand 2.0 supports C#.
• FORTRAN: Understand 2.0 supports FORTRAN 77, FORTRAN
90, and FORTRAN 95, in both free and fixed format. Extensions
supported include Harris FORTRAN and DEC FORTRAN. We
often expand Understand 2.0 to support common compiler
extensions. If you find that the compiler extensions you are using
are not currently supported, contact us at support@[Link].
• Java: Understand 2.0 supports most of JDK 1.3, 1.4, 5, and 6.
Specifically, the generics introduced in JDK 5 are not currently
supported. Source code containing generics may be analyzed
but generics information will be ignored.
• JOVIAL: JOVIAL73 and JOVIAL3 are supported.
• Pascal: Understand 2.0 supports all versions of Borland's Delphi
language and Borland's Turbo Pascal language. It also supports
ISO 7185: 1990 (also known as Unextended Pascal) with DEC
Pascal extensions. You can also enable support for Ingres
embedded SQL statements.
• PL/M: The standard version for PL/M 80/86 is supported.

1-4 Understand 2.0 User Guide and Reference Manual

 For Those Who Don’t Like to Read Manuals

For Those Who Don’t Like to Read Manuals

If you are like many engineers at Scientific Toolworks, you like to
just dig in and get going with software. We encourage that, or at
least we are pragmatic enough to know you will do it anyway! So
feel free to use this manual as a safety net, or to find the less
obvious features. However, before you depart the manual, skim the
next chapter for tips on effectively utilizing what Understand 2.0 has
to offer.
Here are some places other than this manual to look for advice:
• Use the links in the Getting Started display (Help->Getting
Started from the menus)
• Choose Help->Help from the menus.
• Use Help->Example Projects to play with sample code.
• Choose Help->FAQ to see the FAQ on our website.
• Choose Help->View SciTools Blog or go to
[Link] to read the blog on our website.
You can get the latest blog topics by clicking Refresh.

For more advanced users, try these information sources:

• Use the link to “Sign Up For Build Notices“ in the Getting Started
display to see the log of changes in each Understand 2.0 build
and to sign up for email messages about new builds.
• Go to [Link]
to search through old build logs. Choose Help->About
Understand to see which build you are currently running.
• Go to [Link] to read and ask
questions in our Forum.
• Choose Help->Key Bindings for keystroke help.
• Go to [Link] for details
about specific metrics.
• Choose Help->Perl API Documentation for help on scripting.

Understand 2.0 User Guide and Reference Manual 1-5

Chapter 1: Introduction

1-6 Understand 2.0 User Guide and Reference Manual

Chapter 2 Parts and Terminology
This chapter helps you put Understand 2.0 to good use quickly and
easily by describing the basic windows in Understand 2.0.

This chapter contains the following sections:

Section Page
Using Understand 2.0 Windows 2–2
Understand 2.0 Terminology 2–3
Starting Understand 2.0 2–5
Right-Click Menus Are Everywhere 2–7
Quickly Find Things in Your Source 2–9
Info Browser 2–12
Source Editor 2–13
Architecture Browser 2–14
Snapshot Manager 2–15
Graphical Views 2–16
ASCII and HTML Reports 2–17
Perl and C APIs for Custom Reporting 2–18

Understand 2.0 User Guide and Reference Manual 2-1

Chapter 2: Parts and Terminology

Using Understand 2.0 Windows

Understand 2.0 has a main window and many smaller areas that
open within the Understand 2.0 application window. You can
arrange these areas in your workspace to meet your needs.
Pushpin Dock/Undock
Title Bar

Previous
Close
Next Window
Drop-down

Sliding
Frame
• Title Bar: You can drag the title bar of an area around the main
window. If you move to the edge of the main window, a docking
area expands. If you drop the area there, it “docks” to the edge of
the main window.
• Pushpins and Drawers: Click the icon to move an area to
a tab along the same edge of the main window to which this area
was docked. This is a “drawer” that opens automatically if you
point your mouse at the tab title. The drawer closes if you move
your mouse away from the area without clicking on it or if you
click the title tab of the currently open drawer.
Click the icon to “pin” a drawer open. Pinned drawers have
a title bar and title bar icons like the ones shown above.
• Dock/Undock: Click the icon to change the area to an
undocked window. Click the icon again in an undocked window
to return to a docked area.
• Close: Click the “X” icon to close the area or undocked window.
• Drop-down: Click this icon to see the right-click menu for this
area. Right-clicking an item within an area usually displays a
right-click menu specific to that item.
• Sliding Frame: You can drag the frames between window areas
to change their sizes.
• Previous and Next: Each area type has different icons below
the title bar. For the Info Browser area shown, you can browse
through the history of entities viewed. For other areas, you will
see other icons.

2-2 Understand 2.0 User Guide and Reference Manual

 Understand 2.0 Terminology

Understand 2.0 Terminology

Before continuing with the rest of this manual, please take a
moment to familiarize yourself with Understand 2.0’s terminology.
Doing so will make reading the manual more helpful and put you on
the same sheet of music as the technical support team should you
need to email or call.
Architect: Architect is a tool and infrastructure that lets humans
easily name regions of software. This tool can then generate reports
and graphs, and other tools can use architectures when selecting
source code sets.
Architecture: An architecture is a hierarchical aggregation of
source code units (entities). An architecture can be user created or
automatically generated. Architectures need not be complete (i.e an
architecture's flattened expansion need not reference every source
entity in the database), nor unique (that is, an architecture's
flattened expansion need not maintain the set property).
Architecture Files: Architecture files are external (serialized)
architecture files that can be imported into the database each time
the database is reparsed. An optional process and list of arguments
can be provided to regenerate the file before importing.
Architecture Template: An architecture template is an architecture
that may not contain entities. It is a hierarchy from which new
architectures can be derived.
Database: The database is where the results of the source code
parsing, as well as project settings, are stored. By default, this is a
project’s “.udb” file.
Entity: An Understand 2.0 “entity” is anything it has information
about. In practice this means anything declared or used in your
source code and the files that contain the project. Subroutines,
variables, and source files are all examples of entities.
Project: The set of source code you have analyzed and the
settings and parameters chosen. A “project file” contains the list of
source files and the project settings.
Relationship: A particular way that entities relate to one another.
The names of relationships come from the syntax and semantics of
a programming language. For instance, subroutine entities can have
“Call” relationships and “CalledBy” relationships.

Understand 2.0 User Guide and Reference Manual 2-3

Chapter 2: Parts and Terminology

Script: Generally a Perl script. These can be run from within

Understand 2.0’s GUI, or externally via the “maintain_uperl”
command. The Understand Perl API provides easy and direct
access to all information stored in an Understand database.
Snapshot: A snapshot is used to capture the state of the database
at a given point in time. Snapshots are used to compare changes
between different states of the database.
....................................................................................................
Parts The following figure shows some commonly used main parts of the
Understand 2.0 graphical user interface (GUI):

Filters and Source

Menu Bar Browsers Toolbar
Editor Graphical View

Document
Info Area Find in Files Dialog
Browser Status Line

2-4 Understand 2.0 User Guide and Reference Manual

 Starting Understand 2.0

Starting Understand 2.0

When you install Understand 2.0 on Windows, a command to launch
the software is added to your Windows Start menu in the SciTools
folder.
When you start Understand 2.0, you see the Getting Started tab in
the Understand window. To begin creating a new project, click New
Project... and see Creating a New Project on page 3–3 for details.
If you’ve used a project recently, it is listed in the Getting Started
tab, and you can click to open it. If the existing project you want to
open isn’t listed, click Open Project... and browse for it.

Understand 2.0 User Guide and Reference Manual 2-5

Chapter 2: Parts and Terminology

You can also choose File->Open Project and File->Recent

Projects from the menus to open projects.
If you are learning about Understand 2.0, use the links in the
Getting Started box. You can click Open Sample Project and
choose an example project that uses a source code language used
in your own projects.
If you are a more experienced Understand user, use the links in the
News & Announcements box to keep your knowledge current.
If you have closed the Getting Started tab and want to reopen it,
choose Help->Getting Started from the menus. If you don’t want to
see the Getting Started tab every time you run Understand 2.0,
uncheck the Show on Startup box.
When you are finished using a project, you can open another project
or choose File->Close <project_name>.udb. If you have made any
changes to files, you will be prompted to save or discard the
changes for each file individually.
....................................................................................................
Other Ways to Run For information on running Understand 2.0 from the command line,
Understand 2.0 see Chapter 13, Command Line Processing.
If multiple users will run Understand 2.0 from the same Windows
machine, each user may have a separate initialization file. These
files store user preferences. Understand 2.0 looks for the
initialization file location in the following sequence:
1 %APPDATA% (local settings and applications)
2 %WINDIR% (typically c:\Windows)
3 %STI_INIDIR%

2-6 Understand 2.0 User Guide and Reference Manual

 Right-Click Menus Are Everywhere

Right-Click Menus Are Everywhere

Right-clicking gets you a long way in Understand 2.0; almost
everywhere you point, you can learn more and do more by bringing
up menus with your right mouse button.
Tip: Hold down the Ctrl key while right-clicking to create new windows
rather than re-using existing ones.
Remember to right-click, anytime, anywhere, on any entity to get
more information about that entity.

Example: Right-click on an entity in the Source Editor:

Understand 2.0 User Guide and Reference Manual 2-7

Chapter 2: Parts and Terminology

Example: Right-click on an entity in the filter area:

Example: Right-click on an entity in the Info Browser:

2-8 Understand 2.0 User Guide and Reference Manual

 Quickly Find Things in Your Source

Quickly Find Things in Your Source

Understand 2.0 provides several ways to quickly locate items of
interest in your source code. The windows used include the Filter
Area, the Entity Locator, and the Find in Files dialog.
....................................................................................................
Entity Filter The filter area of the Understand 2.0 window helps you quickly find
things in your code by separating that database into lists of Files,
Classes, Functions, Objects, Types, Macros, Subprograms,
Packages, Modules, Blocks, Methods, Interfaces, SQL Tables, and
more. The types of filters available depend on the languages you
have configured your Understand 2.0 project to understand.
After clicking in the filter area, you can type a letter to move to the
first entity beginning with that letter in the current list.
By default, the Info Browser shows all known information about the
selected entity and is a key to navigating in Understand 2.0.

Filter Area

Info Browser

For details, see Entity Filter on page 4–5 and Info Browser on
page 4–8.

Understand 2.0 User Guide and Reference Manual 2-9

Chapter 2: Parts and Terminology

....................................................................................................
Entity Locator The filter provides a quick way to find major items that were
declared and used in your project. However, some items such as
local parameters, variables, and unresolved variables (used but not
declared in the processed source) are not listed in the filters. To
search or browse the entire database for your project, use the Entity
Locator.
To open the Entity Locator, choose Search->Entity Locator.

By default, this area lists all the entities in the project. You can
search for entities matching a particular text or regex string using
the fields above each column.
For details, see Entity Locator on page 5–3.
As in any other window, the right-click menu is also active.
You can select multiple rows and columns and copy their contents
to the clipboard. When you paste, the contents will be pasted as tab-
separated text.

2-10 Understand 2.0 User Guide and Reference Manual

 Quickly Find Things in Your Source

....................................................................................................
Find in Files Similar to the UNIX
command grep, you may
search files for the
occurrence of a string.
Select Find in Files either
from the Search menu or
from a right-click menu.
When you click the
Search icon, a list of all
occurrences matching the
specified string or regular
expression is displayed in
the Find Results window.
Double click on any result
to display the Source View
where the string occurs.
The Find Options let you
set options such as case-
sensitivity and wildcard
pattern matching.
See Find in Files on
page 5–8 for more information.
....................................................................................................
Favorites You can place entities and code locations that you often use on your
Favorites list. To add a favorite, right-click on it and select Add
Favorite. To see the Favorites list, choose Search->Favorites.
Then, double-click a favorite from the list to go to its location.

See Favorites on page 4–17 for more information.

Understand 2.0 User Guide and Reference Manual 2-11

Chapter 2: Parts and Terminology

Info Browser
Just about everything Understand 2.0 knows about code is shown in
the Info Browser (IB). The IB is used for all types of entities.
The Info Browser shows different things depending on the type of
entity selected.
It shows different kinds of information about entities such as source
files, classes, members, functions, types, methods, packages,
interfaces, and more. Information that is hierarchical in nature (such
as a call relationship) can be expanded multiple levels.
Below are Info Browser windows for a file and a C function:

For details, see Info Browser on page 4–8.

2-12 Understand 2.0 User Guide and Reference Manual

 Source Editor

Source Editor
Understand 2.0 has a source editor that not only lets you edit your
source code, it colorizes the source code and tells you about the
code you are editing.
Source can be visited by double-clicking almost anywhere else in
the tool. You can move forward or backward through such “visits” by
using the Next and Previous icons in the toolbar.

As with any other place in Understand 2.0, a right-click menu is

available throughout the editor. To learn about something just right-
click on it to see what information is available.
For details, see Source Editor on page 6–2.

Understand 2.0 User Guide and Reference Manual 2-13

Chapter 2: Parts and Terminology

Architecture Browser
The Architecture Browser allows you to manage architectures. It
shows a list of all the defined architectures in the database and
provides a way to navigate individual architectures.
For example, this window shows the auto-architectures provided
with Understand 2.0: Calendar, Filesystem, Languages. The
architectures are expanded somewhat here to show the top-level
nodes for an example application.

You can use the auto-architectures, create your own architectures,

import and export architectures (as XML files), generate graphs and
metrics for any level in an architecture hierarchy, and combine
architectures through filtering.
For details, see About Architectures on page 7–2.

2-14 Understand 2.0 User Guide and Reference Manual

 Snapshot Manager

Snapshot Manager
The Snapshot Manager allows you to compare versions of files. You
can take a snapshot to capture the state of the database at a given
point in time.

Later, you can compare a snapshot to the current files to find what
changes have occurred.

For details, see About Snapshots on page 8–2.

Understand 2.0 User Guide and Reference Manual 2-15

Chapter 2: Parts and Terminology

Graphical Views
Understand 2.0 analyzes your software code and creates a
database containing information about the entities and the relations
between entities. The database can then be browsed using various
“graphical view” windows. The graphical views are divided into
these kinds:
• Hierarchy views show relations between entities. Each view
follows a relation (for instance “Calls”) from the starting entity
(that you inquired about) through its children and successors.
• Structure views quickly show the structure of any entity that
adds to the structure of your software (for instance a package,
function, procedure, or task).
Examples of each type are shown in the following figure:

Structure Hierarchy
View View

For details, See Using Graphical Views on page 9–1.

2-16 Understand 2.0 User Guide and Reference Manual

 ASCII and HTML Reports

ASCII and HTML Reports

Views in Understand 2.0 provide information about individual
entities. The reports bundle information about all entities in ASCII or
HTML format.

The HTML and ASCII reports also show information not available
interactively, such as project metrics and quality reports. These
reports are suitable for printing or browsing with a web browser.
See Generating Reports on page 10–1 for more information.

Understand 2.0 User Guide and Reference Manual 2-17

Chapter 2: Parts and Terminology

Perl and C APIs for Custom Reporting

Understand 2.0 data is also available directly from scripts and
programs that you (or we) write. A C API (usable from C, C++ or
other languages that can call C libraries) and a Perl interface are
provided with Understand 2.0.
Using the API you have exactly the same access that we have when
we write the existing GUI and report generators.
This manual doesn’t cover the APIs. Choose Help->PERL API
Documentation and Help->FAQ for more information.
The Project->Project Interactive Reports and Project->Project
Graphical Views commands display a list of user-created plugins,
which can be created using the Perl API. For information about
creating plugins, please contact support@[Link]. The
SciTools forum at [Link] and the SciTools
blog at [Link] also contain messages concerning
plugins.
API development is part of the “Analyst” edition. Scripts and API
programs built with the “Analyst” edition can be used by the Pro and
Engineer editions of Understand 2.0.

2-18 Understand 2.0 User Guide and Reference Manual

Chapter 3 Configuring Your Project
This chapter shows how to create new Understand 2.0 project files
that you will use to analyze your source code.

This chapter contains the following sections:

Section Page
About Understand 2.0 Projects 3–2
Creating a New Project 3–3
Project Configuration Dialog 3–8
Languages Category 3–10
Files Category 3–11
File Types 3–17
File Options 3–18
Scheduled Activities 3–19
Metrics 3–22
Reports 3–24
Visual Studio 3–26
Ada Options 3–28
C++ Options 3–32
C# Options 3–39
FORTRAN Options 3–40
Java Options 3–43
JOVIAL Options 3–45
Pascal Options 3–47
PL/M Options 3–50
Setting General Preferences 3–51
Analyzing the Code 3–67

Understand 2.0 User Guide and Reference Manual 3-1

Chapter 3: Configuring Your Project

About Understand 2.0 Projects

Understand 2.0 is like a compiler, except it creates information, not
executable code.
In order for Understand 2.0 to analyze your source code, it needs
much of the information your compiler needs. It needs to know:
• What source files to analyze
• The type of source code
• The standard library paths and include directories
• Where to find Java .jar files that provide classes for which you do
not have source code
• Compiler/environment specific macros that need to be defined
for the pre-processor
• Application-specific macro definitions
• What implementation parameters (such as integer precision) and
column truncation settings to use
• Any namespaces
If you developed the program or have been working with it for some
time, this information is probably obvious to you. However, if you
inherited this source code from another programmer, team, or
company, you will probably have to examine the project building
files (for example, a makefile) in order to come up with the
information needed for accurate parsing of the code.
The easiest way to analyze your code is to use Understand 2.0’s
GUI to build and parse a project.
....................................................................................................
The Understand 2.0 The Understand 2.0 project database is stored in a proprietary
Project Database binary format. The file format uses a network/object format that is
optimized for storing Understand 2.0 information.
Understand 2.0 databases have a file extension of .udb.
The project file permits multiple simultaneous read accesses, but it
does not (yet) support multi-user write access.
Occasionally, a new feature to Understand 2.0 requires a change to
the database format. Such changes are noted in the Change Log.
When you install a build that modifies the database format, existing
projects are automatically reparsed when you open them.

3-2 Understand 2.0 User Guide and Reference Manual

 Creating a New Project

Creating a New Project

To begin analyzing code, you create a project and specify what
source files to parse. Understand 2.0 parses your code and creates
a database you can browse. This database can be refreshed
incrementally in the GUI or updated using command-line tools.
This section shows how to create a new project. The project will be
stored in a Project Database, which has a file extension of .udb.
To create a new project, follow these steps:
1 Click the New Project link in the Getting Started tab that you see
when you start Understand 2.0. Or, choose File->New Project
from the menus.
- By default, this opens the New Project Wizard, which is
described on page 3–4.
- Alternately, you may have disabled the option to run this
wizard, in which case, you see the “Create new project as...”
dialog. Browse to the folder where you wish to create the
project database. Type the name of the project in the File
name field. A .udb file extension will be added automatically.
Click Save. You will see the Understand Project Configuration
dialog, which is described in page 3–8.

Understand 2.0 User Guide and Reference Manual 3-3

Chapter 3: Configuring Your Project

....................................................................................................
New Project Wizard Unless you have disabled the New Project Wizard, this is the tool
you use to create projects. To open it, click the New Project link in
the Getting Started tab that you see when you start Understand 2.0.
Or, choose File->New Project from the menus.
1 In the Create a Project File page of the wizard, type a Name for
the project and browse for a directory to contain the Understand
2.0 project files. It is often handy to have the project file in the
top-level directory of the source code, but this is not required. If
the directory does not exist, you are asked if you want it created.

2 Click Next to see the Languages page of the wizard.

3-4 Understand 2.0 User Guide and Reference Manual

 Creating a New Project

3 Put checkmarks next to languages used in the source code for

this project. You can check multiple languages for which you are
licensed to use Understand 2.0 (see page 1–4). See Languages
Category on page 3–10 for more information. If you use
Microsoft Visual C for your C, C++, or C# code, you can check
the box to import project settings. Then click Next.
4 If you checked the Import project settings from a MSVC
Project box, you see the Visual Studio File(s) page. Otherwise,
skip to the next step.

To synchronize your Understand project with Visual Studio

projects, click Add. In the Add a new Visual Studio file dialog,
click ... and browse for your Visual Studio project file. In the Add
a new Visual Studio file dialog, select the project configuration
you want used when Understand 2.0 analyzes your project. Then
click OK. See Visual Studio on page 3–26 for more information.
You can add multiple Visual Studio projects or use the Edit
button to change the Configuration setting. Then click Next.

Understand 2.0 User Guide and Reference Manual 3-5

Chapter 3: Configuring Your Project

5 In the Source Files page of the wizard, you add source files to a
project by clicking Add a Directory or Add a File.

To add a file, just browse for the file and add it.
When you add a directory, you can browse for a directory, modify
the list of languages used in the source files, add additional filters
for file extensions not expected by Understand 2.0, filter out any
files you want to exclude (for example, temp*.*), and choose
whether all the subdirectories of this directory should be added.
You can also choose whether the directory will be watched for
changes. See Adding Directories on page 3–12 for details.

3-6 Understand 2.0 User Guide and Reference Manual

 Creating a New Project

If you chose a Visual Studio project, those files are automatically

listed in the Source Files page of the New Project Wizard.
If you want to delete a file or a directory (and its subdirectories),
select that item and click the “X” icon.
6 Choose whether to Analyze project now or further configure the
project. Choosing Configure more settings takes you to the
Project Configuration dialog, which is described starting on
page 3–8. In either case, you can go to the Project Configuration
dialog anytime you like.

Understand 2.0 User Guide and Reference Manual 3-7

Chapter 3: Configuring Your Project

Project Configuration Dialog

The Understand Project Configuration dialog opens when you
create a new project or when you choose the Project->Configure
Project menu item.

The categories on the left in the Project Configuration dialog allow

you to specify various project settings to be used during analysis.
The Project Configuration dialog contains the following categories:
• Languages: Specify the types of languages to be parsed. For
details, see page 3–10.
• Files: Specify the locations of source files to be analyzed. For
details, see page 3–11.
• File Types: Specify how to handle source file types and what file
extensions are used. For details, see page 3–17.
• File Options: Specify the file encoding and editing mode for
source files. For details, see page 3–18.

3-8 Understand 2.0 User Guide and Reference Manual

 Project Configuration Dialog

• Scheduled Activities: Schedule events to take place at regular

intervals. For details, see page 3–19.
• Metrics: Specify the metrics you want computed for this project.
For details, see page 3–22.
• Reports: Specify the reports you want generated for this project.
For details, see page 3–24.
• Visual Studio: Specify a Visual Studio project to synchronize
this Understand 2.0 project with. For details, see page 3–26.
• Language-Specific Options: Specify options for the languages
you selected in the Languages category. For details, see:
- Ada Options, page 3–28
- C++ Options, page 3–32
- C# Options, page 3–39
- Fortran Options, page 3–40
- Java Options, page 3–43
- JOVIAL Options, page 3–45
- Pascal Options, page 3–47
- PL/M Options, page 3–50
After you change the project configuration, click the OK button and
the configuration will be saved. Whenever you modify the files in the
project configuration, including at the time of project creation, a
dialog alerting you to the change in configuration appears.

Click OK and Understand 2.0 begins parsing (that is, analyzing) the
code.
If you want to close the Project Configuration dialog without saving
any changes, click Cancel, and then click Yes in the box that asks if
you really want to cancel changes.

Understand 2.0 User Guide and Reference Manual 3-9

Chapter 3: Configuring Your Project

Languages Category
In the Languages category of the Project Configuration dialog, you
can check boxes for the languages used in your project. A project
can contain source code in one or more languages.

Only languages you are licensed to use are selectable in this dialog.
The Engineer edition of Understand 2.0 supports only C/C++, C#,
and Java. The “Analyst” and “Pro” editions of Understand 2.0 come
in two language variants:
• L1: C/C++/C#, Java, Pascal/Delphi, FORTRAN
• L2: C/C++/C#, Java, Pascal/Delphi, FORTRAN, Ada, PL/M,
JOVIAL
When you select a language, categories for that language are
added to the list on the left in the Project Configuration dialog.
The languages you choose here not only affect how the source files
are parsed. They also affect the filter types available, the metrics
available, and the report types available.
If you select multiple languages, references between those
languages are analyzed. For example, if C code calls a Java
function, that reference will be found.

3-10 Understand 2.0 User Guide and Reference Manual

 Files Category

Files Category
In the Files category of the Project Configuration dialog, you can
add source code directories and/or individual files to the project. You
can also delete specific files from the analysis and modify the
language-specific options for individual directories and files.

You can add sources here, or you can tie the project to those
specified in an MS Visual Studio project file (MS Windows versions
of Understand 2.0 only). See Visual Studio on page 3–26.
The top area shows the directories and files you have added in a
tree that you can expand. It also shows how many files are currently
in the project.
The bottom area shows any option overrides you have set for the
selected directory or file.

Understand 2.0 User Guide and Reference Manual 3-11

Chapter 3: Configuring Your Project

Icons at the top of the dialog perform the following actions:

Open the Add a Directory dialog.
Open the Add a File dialog.
Choose Add a File or import a list of files
Delete the selected directory or file from the project analysis.
Copy the override settings for the selected directory or file.
Paste the override settings to the selected directory or file.
Configure override settings for the selected directory or file.
Set portability options for file paths. See page 3–16.
Note that your changes are not saved until you click OK.
Click Rescan if you have added files to a directory that are not
shown in the tree in this dialog.
....................................................................................................
Adding Directories To add source directories to the project, click . You see the Add
a Directory dialog:

1 In the Directory field, type the full directory path. Or, you can
click the ... button and use the Browse for Folder dialog to locate
a directory containing source files and click OK.

3-12 Understand 2.0 User Guide and Reference Manual

 Files Category

2 In the Configured Filters field, click the ... button if you want to
add or delete languages from the list shown. In the Select Filters
from Configured File Types dialog, put a checkmark next to any
languages you want to be recognized as part of the project.
Notice that additional languages are listed beyond those shown
in the Languages category. These include JavaScript, MSDos
Batch, Perl, Tcl, Text, and XML.
If this directory contains source files with extensions that are not
listed, click Configure. Also, see File Types on page 3–17. For
example, you might add .a64 as an assembly file type.
3 In the Additional Filters field, type a pattern-matching string that
matches only the files you want to keep in the analysis. For
example, std*.* includes only files that begin with “std”.
4 In the Exclude field, type a pattern-matching string that matches
files you want to exclude from the analysis. For example, temp*.*
excludes all files that begin with “temp”.
5 To select and add multiple subdirectories to a project
configuration, check the Include subdirectories box (on by
default). This causes all source files matching the filter in all
subdirectories of the specified path to be added to the project.
6 If you want this directory to be watched for any new files or
deleted files, check the Watch this directory box. Whenever a
source file is added to or deleted from this directory, the change
is reflected in this project. Watched directories are indicated by
the icon in the files list. Directories excluded from being
watched are indicated by the icon. By default, the
subdirectories of a watched directory are also watched. See
page 3–14 for watch setting overrides.
7 On UNIX, you can choose whether symbolic links should be
followed when adding files.
8 After you have specified the fields, click the OK button to add the
source files in that directory to the project. You can click Cancel
if the add file process is taking too long.
Tip: You may add files from multiple directory trees.
If you are using Microsoft Windows, you may drag and drop a
directory, a file, or a selection of files, from another window into the
Project Configuration dialog to add it to the project. If you drag a
folder, the Add a Project Directory dialog opens automatically. If you
drag an individual file, that file will be added to the project whether it
matches the file filter or not.
All directory paths are absolute.

Understand 2.0 User Guide and Reference Manual 3-13

Chapter 3: Configuring Your Project

....................................................................................................
Adding Files To add individual source files to the project, click . You see a file
selection dialog, which allows you to select one or more source files
to add to the project. Browse for and select a file or files. Then click
Open. The file(s) are added to the project.
If you click the down arrow next to the icon, you can choose
to import a text file that contains a list of source files to import. For
example, you might generate such a file from a compiler application
or code management system. The file should contain one absolute
file path per line. See Adding Files to a Project on page 13–3 for an
example of such a file.
....................................................................................................
Deleting Directories To delete a directory or file from the project, select the items you
and Files want to delete and click .
....................................................................................................
Setting Overrides Normally, each file in the project is processed according to the rules
you specify in the Project Configuration window for the language of
the file. For example, for C++ you can set include directories and
macro definitions. However, you can override the default settings on
a directory-by-directory or file-by-file basis if you like.
Directory: To override settings for a directory, follow these steps:
1 Select a directory.
2 Click or right-click and select Configure override settings.

3 In the Watched Properties category, you can choose how files

in this directory should be watched for new files to add to the

3-14 Understand 2.0 User Guide and Reference Manual

 Files Category

project or deleted files to remove from the project. For Watch

Settings, you can choose to watch a directory, not watch a
directory, or inherit watch settings from the parent directory. In
addition to specifying whether to watch a directory, you can set
filters and exclude filters for an individual directory that control
what types of new and deleted files will be found.
4 In the various Override categories, you can make directory-
specific language-related settings.
The File Type category lets you override the language of this file
indicated by the file extension. The File Encoding category lets
you override the encoding setting described in File Options on
page 3–18.
File: To override settings for a file, follow these steps:
1 Select a file.
2 Click or right-click and select Configure override settings.

3 In the various Override categories, select a category and make

changes. The categories available are different depending on the
language of the source file. See page 3–28 through page 3–50
for details. The Watched Properties category is available for file
overrides if you are using Relative or Named Root portability.
4 Click OK to save your overrides.
Special icons in the directory tree indicate which directories are
being watched , have overrides , or both .
....................................................................................................
Scanning Watched If you set directories to be watched, you can scan those directories
Directories for new files to be added or deleted files to be removed by choosing
Project->Rescan Watched Project Directories.
You can schedule automatic scans of watched directories. See
Scheduled Activities on page 3–19 for details.

Understand 2.0 User Guide and Reference Manual 3-15

Chapter 3: Configuring Your Project

....................................................................................................
Setting File You can control the portability of Understand 2.0 projects by clicking
Portability the icon at the top of the Files category of the Project
Configuration dialog. You will see the following dialog.

Note: The icon is inactive if your project contains any snapshots.

Because the portability setting must be the same for the current
database and all the snapshots, you can only change the portability
options before creating snapshots or if you delete all the snapshots.
A more portable project can allow you to share the project with other
users and to use the project unchanged after moving the source
code files.
The choices are as follows:
• Absolute: This option is the default. It stores full file paths for all
directories. If the source files change location, the paths will be
incorrect.
• Relative: This option stores the relative path to directories from
the location of the Understand 2.0 project database. If you store
the project database in the source file tree and move it along with
the source files, the project can still be used.
• Named Root: This option allows you to specify “Named Roots”
that are similar to environment variables to point to a root
directory. Different users may then use different definitions for a
named root. Click the Edit Named Roots button and see
page 3–60 for details.
Check the Use File Portability Mode to convert paths box if you
want the file paths currently stored in the project to be updated when
you click OK.

3-16 Understand 2.0 User Guide and Reference Manual

 File Types

File Types
In the File Types category of the Project Configuration dialog, you
can control how file extensions are interpreted by Understand 2.0.

The list shows all the file extensions already understood. Files with
the types understood for the languages you checked in the
Languages category are analyzed as part of the project. Other files
are not analyzed.
To modify an existing type, select the type and click Edit.
To add a file extension to the list, click New. Type a file extension
and select the language to use for the file extension. Then click OK.

Understand 2.0 User Guide and Reference Manual 3-17

Chapter 3: Configuring Your Project

File Options
In the File Options category of the Project Configuration dialog, you
can control how files are opened and saved by Understand 2.0.

• File Encoding: Select the type of encoding to use when saving

source files. Many encoding formats are supported. You should
change this only if your other applications have problems
opening or displaying files saved by Understand 2.0. See Editor
Category on page 3–61 for more information. The default file
encoding is “System”, which means the default encoding for your
computer. If you change the setting here, new projects you
create use the last setting you saved. You can override the file
encoding setting on a file-by-file or directory-by-directory basis
(see Setting Overrides on page 3–14).
• Open all project files as read only files: Check this option if
you do not want files to be edited and saved within Understand
2.0.

3-18 Understand 2.0 User Guide and Reference Manual

 Scheduled Activities

Scheduled Activities
In the Scheduled Activities category of the Project Configuration
dialog, you can cause certain events to be performed on a regular
basis. You can also open this dialog quickly by choosing Tools->
Scheduled Activitites.

To schedule events for the project you currently have open, follow
these steps:
1 Check the Process At box.
2 Select a processing time and check the boxes for one or more
days of the week.
Note: Understand 2.0 must be running at the processing time or the
events will not occur.

Understand 2.0 User Guide and Reference Manual 3-19

Chapter 3: Configuring Your Project

3 Check the boxes for the events you want performed. The events
occur in the sequence shown. For example, watched directories
are scanned before the project is analyzed, and the project is
analyzed before metrics are processed.
The following activities are available for scheduling:
• Rescan watched directories: Check this box to automatically
check for files that have been added to or deleted from project
directories. See Adding Directories on page 3–12 for how to
specify which directories to watch. If you have watched
directories, you should always run this task before the “Analyze
all files” task. To run this action without scheduling it, choose
Project->Rescan Watched Project Directories.
• Analyze all files: Check this box to automatically analyze all
project files as described in Analyzing the Code on page 3–67.
Run this task before generating any metrics so that the statistics
will reflect the current state of the project. To run this action
without scheduling it, choose Project->Analyze All Files.
• Create automatic snapshots: Check this box to automatically
generate a snapshot of all the code in the project as described in
Creating Snapshots on page 8–3. Snapshots allow you to
compare changes between entities as they were at different
times. The snapshot name is generated automatically. To run
this action without scheduling it, choose Change->Make
Snapshot.
• Metric processing: Check this box to automatically calculate
metrics for the project. The metrics selected in Metrics->Selected
Category on page 3–23 are processed. Run this task if you plan
to schedule either of the following metrics export tasks.
• Metric CSV export: Check this box to automatically export
metrics as a comma-separated value file. If this box is checked,
you can select the directory path and output filename for the
export. By default, any existing file with the same name is
renamed to provide a backup. You can check the Overwrite box
if you simply want to replace the old export file. To further
configure the export, see Metrics on page 3–22. To run this
action without scheduling it, choose Metrics->Export Project
Metrics and see Exporting Metrics to a CSV File on page 11–6.

3-20 Understand 2.0 User Guide and Reference Manual

 Scheduled Activities

• Metric export HTML: Check this box to automatically export

metrics as web pages. If this box is checked, you can select the
directory path for the export. By default, any existing file with the
same name is renamed to provide a backup. You can check the
Overwrite box if you simply want to replace the old export file.
To run this action without scheduling it, choose Project->Project
Reports and see Exporting Metrics to HTML on page 11–5.
When scheduled activities are about to run, you see a

If you have scheduled any activities, you see the following message
when you exit from Understand 2.0.

To see a list of all projects for which you have scheduled activities,
choose Tools->Master Scheduler List. To change these times,
you must open the project and then use the Project Configuration
dialog for that project.

Understand 2.0 User Guide and Reference Manual 3-21

Chapter 3: Configuring Your Project

Metrics
In the Metrics category of the Project Configuration dialog, you can
control how metrics are generated when a CSV file is exported.
These options set the defaults for both manual updates (page 11–6)
and scheduled automatic updates (page 3–19).
The Metrics category has two sub-categories: Options and
Selected.

You see this window when you choose the Project->Configure

Project menu item and then the Metrics category. If you attempt to
generate metrics before configuring metrics, this window opens
automatically.
The Options subcategory has the following fields:
• Output file: Specify the location and name of the file you want to
use for metrics output. Understand 2.0 sends its metrics output
to a .csv (comma-separated values) file. This file can be opened
with Microsoft Excel and other spreadsheets.
• Show File Entities Name as: Specify whether files should be
displayed with Short names (just the filename), Full names
(including the absolute path), or Relative names (relative
directory path).

3-22 Understand 2.0 User Guide and Reference Manual

 Metrics

• Show Declared in File: Check this box if you want the file in
which each entity is declared to be included in the output. You
can specify whether you want these files displayed with Short
names, Full names, or Relative names.
• Show Function Parameter Types: Check this box if you want
the type of each function parameter listed.
• Write Column Titles: Check this box if you want column
headings in the CSV file.
....................................................................................................
Metrics->Selected The Selected subcategory has lists like the following:
Category

1 In the Available Metrics list (left), select metrics you want to

include in the output you generate. You can hold down Shift to
select a continuous group or Ctrl to select discontinuous items.
2 Click Add to copy the selected metrics to the right column.
3 You can reorder the metrics in the right column using the Move
Up and Move Down buttons.
See [Link]/documents/[Link] for descriptions.

Understand 2.0 User Guide and Reference Manual 3-23

Chapter 3: Configuring Your Project

Reports
In the Reports category of the Project Configuration dialog, you can
control how reports are generated. The Reports category has the
following sub-categories: Output, Options and Selected.

You see this window when you choose the Project->Configure

Project menu item and then the Reports category. You can also
reach this window by clicking Configure in the Project Reports
window.
....................................................................................................
Reports->Output The Output subcategory has two main areas:
Category • Generate HTML: This option causes the report generation to
create a large group of HTML files that are interlinked.
- You may generate Single or multiple HTML files for each
report type. It is recommended that you split up the files for
large projects. Choose Alphabetic to generate multiple HTML
files per report that are split up alphabetically by the first letter

3-24 Understand 2.0 User Guide and Reference Manual

 Reports

of the entity name. Choose Every n Entities to generate

multiple HTML files per report that are split up every “n”
number of entities. By default, a single HTML file is generated
for each letter of the alphabet.
- The “home” file for the reports is [Link], but you can select
an alternate Title Page.
- The default Save in directory is the <proj_file>_html folder
below the folder where your .udb file is stored, but you can
select an alternate location.
• Text reports: This option causes the report generation to create
simple text files containing the report data.
- You may generate one text file of the specified location and
name (by choosing Single Text File). Alternately, you may
generate multiple text files (by choosing Separate Files) and
specify a directory to contain all the files. The file extensions of
each text file will denote the separate reports. Depending on
which option you select, you can also select either a file or
directory location for the output.
You can choose to generate either or both of the HTML and text
report formats.
....................................................................................................
Reports->Options The Options subcategory has the following fields:
Category
• Display full filenames: If this box is checked, the invocation tree
and metrics reports show full entity names. The default is to use
short names.
• Write generation time on report: If this box is checked, the
generation date and time are included at the top of text report
files. This is on by default.
....................................................................................................
Reports->Selected The Selected subcategory lets you check the boxes for the reports
Category you want to generate. The list of reports differs depending on which
languages are used in your project. See Chapter 10 for descriptions
of these report formats.

Understand 2.0 User Guide and Reference Manual 3-25

Chapter 3: Configuring Your Project

Visual Studio
In the Visual Studio category of the Project Configuration dialog,
you can tell Understand 2.0 to use the source, macro, and include
path settings from a Microsoft Studio project file.
You see this window when you choose the Project->Configure
Project menu item and select the Visual Studio category.

Follow these steps:

1 Click Add.
2 In the Add a new Visual Studio file dialog, click the “...” button
next to Visual Studio File. Then browse to select a Visual
Studio project file and click Open. MS Visual Studio project files
with extensions of .csproj (C# project), .dsp, .dsw (workspace
file), .sln, .vcp (Windows CE project), .vcproj, and .vcw
(workbench file) are supported.
3 Select the Configuration you want Understand 2.0 to use when
analyzing your project.

3-26 Understand 2.0 User Guide and Reference Manual

 Visual Studio

4 You can expand the Contains list to see the includes, defines,
and files for the configuration currently selected.
Note: If you sync with a Visual Studio workspace file, the default
target is used because there is no mechanism for specifying
targets for each .dsp project within a .dsw file.

5 Click OK to add this to your project.

Once set, the source files, macros and include paths from the Visual
Studio project are used by Understand 2.0. This is in addition to any
project settings you configure in the other categories.
Note: Settings in other categories for include path and macros take priority
over the Visual Studio project settings. This permits you to use the
bulk of the Visual Studio settings while selectively overriding as your
needs require.

Understand 2.0 User Guide and Reference Manual 3-27

Chapter 3: Configuring Your Project

Ada Options
In the Ada->Options category of the Project Configuration dialog,
you can tell Understand 2.0 how to analyze Ada source code. You
see this window when you choose the Project->Configure Project
menu item and select the Ada category.

The fields in this category are as follows:

• Version: Choose the version of Ada used in your project.
Understand 2.0 supports Ada 83, Ada 95, and Ada 05.
• Preprocessor: Choose which type of preprocessor statements
are used in your Ada code. The choices are None, C, and Verdix.

3-28 Understand 2.0 User Guide and Reference Manual

 Ada Options

• Standard: Choose the directory that contains the standard

library used by this project. Default standards are provided within
<install_directory>/conf/understand/ada.
Sometimes it is helpful to parse code in context of its compilation
environment rather than the environment defined as “Standard”
in the Ada Language Reference Manual. This is most often
needed when your compiler vendor offers bindings to other
languages or low level attributes of a chip or system. To do so,
place all the source files containing the Ada specifications for the
new standard in one directory. Then point to this directory in the
Standard field.
• Case of externally linkable entities: Choose which case
should be used for “exporting” entities in this language that can
be linked to (for example, called as functions) by other
languages. For example, if an entity is declared in this language
as “MYITEM” and you choose “all lowercase” here, other
languages would be expected to call that entity as “myitem”.
• Count and/or operators in strict complexity: Place a check in
this box if you also want “and” and “or” operators considered
when calculating the strict complexity metric shown in the
Program Unit Complexity report. Strict complexity is like
cyclomatic complexity, except that each short-circuit operator
(“and then” and “or else”) adds 1 to the complexity.
• Count exception handlers in complexity: If this box is
checked (it is on by default), exception handlers are considered
when calculating the complexity metrics shown in the Info
Browser and the Program Unit Complexity report.
• Count for-loops in complexity: Remove the check from this
box if you do not want FOR-loops considered when calculating
the complexity metrics shown in the Info Browser and the
Program Unit Complexity report. Complexity measures the
number of independent paths through a program unit.
• Create and cross-reference record object components: If
this box is checked (off by default), separate entities are created
for components of all objects of a record type. By default, all
references to object components are treated as references to the
record type component.
• Create relations between formal and actual parameters:
Place a check in this box if you want the analysis to create
relations between formal and actual parameters. The actual

Understand 2.0 User Guide and Reference Manual 3-29

Chapter 3: Configuring Your Project

parameters linked to formal parameters include items used in

expressions passed as actual parameters. This option is off by
default to speed up analysis.
• Less memory usage versus speed: Place a check in this box if
you want to use Understand 2.0 in a very low memory
consumption mode. In order to conserve memory, Understand
2.0 frees memory used to process a program unit if that program
unit is not needed. Using this option may slow down operation
significantly. It is off by default.
• Save comments associated with entities: You can choose
whether source code comments that occur before and after an
entity should be associated with that entity.
• Prompts on parse errors: By default, you are prompted for how
to handle errors that occur when analyzing files. When
prompted, you may choose to ignore that error or all future
errors. Turn this option off to disable this prompting feature. If
you turned it off during analysis, but later want to turn error
prompting back on, check it here.
• Display entity names as: Choose whether entity names should
be displayed in Understand 2.0 with the same case as the
source code (original), all uppercase, all lowercase, only the first
letter capitalized, or mixed case.
• Main subprograms: Provide a comma-separated list of the
names of the main subprograms in the project.
....................................................................................................
Ada->Macros Ada code may contain conditional compiler instructions in pragma
Category statements. For example:
PRAGMA IF DEVICE == D129
The supported pragmas are IF, IFDEF, ELSIF, ELSE, and ENDIF.
These pragmas are similar to preprocessor directives such as #ifdef
in C code.
For Understand 2.0 to successfully analyze your software it needs to
know what macro definitions should be set.
In the Ada->Macros category of the Project Configuration dialog,
you can specify what macros to define for use with pragmas. You
see this window when you choose the Project->Configure Project
menu item and select the Ada category and the Macros
subcategory.

3-30 Understand 2.0 User Guide and Reference Manual

 Ada Options

The Macros category lists macros and their optional definitions.

Each macro may be edited or deleted. To define a macro, click New.

Type the name of the macro in the first field and the definition (if
any) in the second field. Then click OK.
A macro must have a name, but the definition is optional. Macros
that have no definition value are commonly used in conjunction with
PRAGMA IFDEF statements to test whether a macro is defined.
To change the definition of an existing macro without changing the
name, select the macro and click Edit.
You can import a list of macros and their optional definitions from a
text file by clicking Import and selecting the file. The file must
contain one macro definition per line. A # sign in the first column of a
line in the file indicates a comment. Separate the macro name and
its definition with an equal sign (=). For example, DEBUG=true.
You can set macros on the und command line with the -define
name[=value] option.

Understand 2.0 User Guide and Reference Manual 3-31

Chapter 3: Configuring Your Project

C++ Options
In the C++->Options category of the Project Configuration dialog,
you can tell Understand 2.0 how to analyze C and C++ source code.
You see this window when you choose the Project->Configure
Project menu item and select the C++ category.

The fields in the C++->Options category are as follows:

• Compiler: Select the compiler/platform that you use. This will set
up compiler-specific macros for use by the Understand 2.0
parser. Note that not all features of a particular compiler will
necessarily be handled.
• Compiler Include Paths: Type the path the compiler uses to
find include files. For example, %include%.
• Allow nested comments: By default, this is off. If turned on it
permits C style (/* */) comments to be nested. This isn’t permitted
by the ANSI standard, but some compilers do permit it.

3-32 Understand 2.0 User Guide and Reference Manual

 C++ Options

• Prepend the names of externally linkable entities with: You

may optionally type a string that you want used as a prefix to
reference all linkable entities in other source code languages.
• Append the names of externally linkable entities with: You
may optionally type a string that you want used as a suffix to
reference all linkable entities in other source code languages.
• Create implicit special member functions: Check this box if
you want a default constructor and destructor to be created in the
database and given implicit declaration references, if they are
not declared in the source code for class and struct entities. This
option provides entities for the parser to reference when they are
called. The default is off.
• Create references in inactive code: If you wish to exclude
cross-reference information for code that is IFDEFed out by the
current macro settings, turn this option off. By default, this option
is on and cross-reference information for inactive code is
included.
• Create references to local objects: By default, all local object
declarations are included in the database. If you wish to exclude
variables declared within functions from the database, turn this
option off. Local objects included for analysis can then be either
included or excluded from the HTML output generated. Specify
whether to include local objects in the HTML output on the main
window of Understand 2.0.
• Create references to macros during macro expansion:
Checking this box causes references to be stored during macro
expansion. In some cases, this is useful. Be aware that enabling
this option can add many references and make the database
large and slower. The default is off.
• Create references to parameters: If you wish to exclude cross-
reference information for parameters, turn this option off. By
default, this option is on and all cross-reference information for
parameters is included.
• Save comments associated with entities: You can choose
whether source code comments that occur before and after an
entity should be associated with that entity.
• Save duplicate references: By default, duplicate cross-
references are condensed to a single cross-reference. To keep
duplicates, check this box.

Understand 2.0 User Guide and Reference Manual 3-33

Chapter 3: Configuring Your Project

• Save macro expansion text: If you put a check in this box, you
can right-click on a macro and choose Expanded Macro Text
from the pop-up menu to see how the macro expands.
• Use include cache: By default, include files are cached during
the analysis phase as they are often referenced in multiple
source files. This speeds up analysis, but also uses more
memory. If you have problems with excessive memory use
during analysis, turn this option off. Note that there are also
situations where turning the include cache on or off can affect
analysis results, particularly where include actions are
dependent on where they are included.
....................................................................................................
C++->Includes The C++->Include category in the Project Configuration dialog
Category (which you open with Project->Configure) allows you to specify
include directories. You can specify multiple directories to search for
include files used in the project.
Include paths are not recursively searched; that is, any
subdirectories will not be searched for include files unless that
subdirectory is explicitly specified in the list of include directories.
To add a directory, click the New button and then the ... button,
browse to the directory, and click OK.

During analysis, the include directories will be searched in the order

that they appear in the dialog. You can click Move Up or Move
Down to change the order in which directories will be searched.
Typically only include files that are not directly related to your project
(such as system-level includes) and that you do not want to analyze
fully are defined here. For project-level includes that you want to be
analyzed, add those include files as source files in the Sources
category.
You may use environment variables in include file paths. Use the
$var format on UNIX and the %var% format on Windows.

3-34 Understand 2.0 User Guide and Reference Manual

 C++ Options

You can import a list of include directories from a text file by clicking
Import and selecting the file. The file must contain one directory
path per line. (In all such imported text files, a # sign in the first
column of a line in the file indicates a comment. Full or relative paths
may be used. Any relative paths are relative to the project file.)
The C++->Include category provides the following options to control
how includes are handled:
• Add found include files to source list: Enabling this option
causes include files found during project analysis to be added to
the project automatically. This allows you to see more detailed
information about such include files. The default is off.
• Add found system include files to source list: If you choose
to add include files that are found to the source list, you can also
choose whether system include files should be added. The
default is off.
• Prompt for missing includes: By default, for any include files
that cannot be found during analysis, you will be prompted for
how to handle that missing file. When prompted during analysis,
you may choose to ignore the missing file, or you may specify the
path where the file can be found. Turn this option off to disable
this prompting feature. Any missing include files found during
analysis when the prompt feature is turned off will be ignored.
• Search for include files among project files: This option
directs the parser to look among project files as a last resort for
missing include files. The default is on.
• Treat system includes as user includes: This option tells the
parser to look for system includes (surrounded by < >) using the
same strategies as normal includes (surrounded by quotes). If
this item is off, the parser looks for system includes only in
directories defined by the compiler configuration. The default is
on.
• Use case-insensitive lookup for includes: This option tells the
parser whether to ignore the case of filenames in #include
statements. The default is off.
....................................................................................................
C++->Includes->Auto In the C++->Includes->Auto category you can specify include files
Category that should be included before each file in a project.
To add a file, click New and browse for the file. Then click Open.
You can import a list of auto include files from a text file by clicking
Import and selecting the text file that contains one file path per line.

Understand 2.0 User Guide and Reference Manual 3-35

Chapter 3: Configuring Your Project

....................................................................................................
C++->Includes-> In the C++->Includes->Ignore category you can specify individual
Ignore Category include files that you wish to ignore during analysis.
To add a file to be ignored, click the New button and type the
filename of the include file. Then click OK. The filename can use
wildcards, such as moduleZ_*.h, to match multiple files.

Any missing files you choose to ignore when prompted during

analysis will be added to this list.
You can import a list of files to ignore from a text file by clicking
Import and selecting the text file that contains one filename per line.
....................................................................................................
C++->Includes-> In the C++->Includes->Replacement Text category you can
Replacement Text specify text that should be replaced in include file text.
For example, you might use this feature to replace VAX/VMS
include paths like [sys$somewhere] with valid UNIX or Windows
paths without modifying the source code.
To add an item, type the string found in the actual include files in the
Include String field. Type the text you want to replace it with in the
Replace With field. Then click OK.

You can import a list of include strings and their replacements from
a text file by clicking Import and selecting the file. The file must
contain one include string per line. The file should separate the
include string and its replacement with an equal sign (=).

3-36 Understand 2.0 User Guide and Reference Manual

 C++ Options

....................................................................................................
C++->Macros C source code is often sprinkled with pre-processor directives
Category providing instructions and options to the C compiler. Directives such
as the following affect what the software does and how it should be
parsed:
#define INSTRUMENT_CODE
#ifdef INSTRUMENT_CODE
... statements ...
#endif
Macros are often defined with directives (#define) in include files (.h
files) or are passed in via the compiler (typically with the -D option).
For Understand 2.0 to successfully analyze your software it needs to
know what macro definitions should be set.
The C++->Macros category in the Project Configuration dialog
(which you open with Project->Configure) allows you to define
preprocessor macros that are used when compiling the code.
To add a macro definition, click the New button and type the name
of the macro and optionally a definition. Then click OK.

Note that a macro must have a name, but that the definition is
optional. Macros that are defined but have no definition value are
commonly used in conjunction with #ifdef pre-processor statements
to see if macros are defined.
Note: A number of preprocessor macros are automatically supported. In
additions to the common macros, Understand 2.0 supports the
following macro formats for embedded assembly code:
#asm(<embedded assembly code>);
#asm “<embedded assembly code>”;
#asm
<embedded assembly code>
#endasm

Understand 2.0 User Guide and Reference Manual 3-37

Chapter 3: Configuring Your Project

You can import a list of macros and their optional definitions from a
text file by clicking Import and selecting the file. The file must
contain one macro definition per line. A # sign in the first column of a
line in the file indicates a comment. The file should separate the
macro name and its definition with an equal sign (=). For example,
DEBUG=true.
The priority for macro definitions is as follows, from lowest to highest
priority:
1 Built-in language macros (__FILE__, etc.)
2 Compiler configuration file
3 Macro definitions in a synchronized Visual Studio project
4 Undefines of compiler defines (via the Configure Undefines
button)
5 Project defines (Macros category)
6 Define on und command line using -define
7 Define in source file (#define / #undefine in source)
....................................................................................................
C++->Macros-> You can list undefined macros in the C++->Macros->Undefines
Undefines Category category in the Project Configuration dialog. Click New and type the
name of a macro that is not defined. Then click OK.

You can import a list of undefined macros from a text file by clicking
Import and selecting the file. The file must contain one macro name
per line. A # sign in the first column of a line in the file indicates a
comment.

3-38 Understand 2.0 User Guide and Reference Manual

 C# Options

C# Options
If you have C# source code, you can set the following C# option in
the C#->Options category of the Project Configuration window:

The C#->Options category provides the following options for ways

to locate the .NET Framework directory for standard classes:
• Use default Framework directory: If such a default is found, it
is shown next to this option.
• Use Framework directory: If you choose this option, click ...
and browse for the Framework directory you want to use.
• Use sources in standard directory: If you choose this option,
click ... and browse for the standard directory used by the
compiler. A copy of the standard library is included in the
Understand 2.0 installation.
The C/C++ options do not apply to C# code.
....................................................................................................
C#->References In the C#->References category, click New. Click ... and browse for
Category a .dll file. Type the alias for that file used in the code and click OK.

You can import a list of reference files and their aliases from a text
file by clicking Import and selecting a file that contains one
reference and its alias per line. The file should separate the
reference file and its alias with an equal sign (=).
By default, reference files are analyzed as part of the project. If you
do not want them to be analyzed, uncheck the Analyze found
reference files box in this category.

Understand 2.0 User Guide and Reference Manual 3-39

Chapter 3: Configuring Your Project

FORTRAN Options
In the Fortran->Options category of the Project Configuration
dialog, you can specify how to analyze FORTRAN source code. You
see this window when you choose the Project->Configure Project
menu item and select the Fortran category.

The fields in the Fortran->Options category are as follows:

• Version: Select the variant of FORTRAN used by the source
code in this project. If you change the version after creating a
project, the project will be reanalyzed when you click OK. The
choices are FORTRAN 77, FORTRAN 90, or FORTRAN 95. If
you have a mix of code, choose the newest language variant.
That is, if you have F77 and F95 code, choose F95.

3-40 Understand 2.0 User Guide and Reference Manual

 FORTRAN Options

• Format: Some older FORTRAN variants and all new variants

permit free form statements, which may cross lines). Fixed form
statements are terminated by a line end or column number. The
default is “auto format,” which automatically detects the parsing
format (fixed or free) on a file-by-file basis. This allows you to mix
free and fixed format. Auto format also determines the correct
truncation point for fixed format files. Choose “fixed” or “free” only
if all your source files have the same format.
• Truncate column: If you choose fixed form, you may choose
what column terminates statements. Common columns 72 and
132 are available or you may specify a column or no truncation.
• Allow C-style comments: Check this option if your FORTRAN
code contains comments of the form /* ... */.
• Allow colons in names: Check this box to allow colons (:) to be
used in identifiers in F77 code. Enabling this option could cause
problems in F77 code that does not use this extension, so the
default is off.
• Allow function declaration without parentheses: Check this
box if you want to allow functions to be declared without the use
of parentheses. By default, parentheses are required.
• Allow quote in octal constants: Check this box if a double
quote mark ( " ) should be treated as the start of a DEC-style
octal constant. For example, "100000. If this box is not checked
(the default), a double quote mark begins a string literal.
• Case sensitive identifiers: Check this box if you want identifier
names to be treated case-sensitively. By default, case is ignored.
• Use preprocessor: Use this option to disable or enable
preprocessor support.
• Intrinsics file: Type or browse for a file that contains intrinsic
functions you want to be parsed. Default intrinsics files are
provided in the <install_directory>/conf/understand/fortran
directory: [Link], [Link], and [Link].
• Case of externally linkable entities: Choose which case
should be used for “exporting” entities in this language that can
be linked to (for example, called as functions) by other
languages. For example, if an entity is declared in this language
as “MYITEM” and you choose “all lowercase” here, other
languages would be expected to call that entity as “myitem”.
• Prepend the names of externally linkable entities with: You
may optionally type a string that you want used as a prefix to
reference all linkable entities in other source code languages.

Understand 2.0 User Guide and Reference Manual 3-41

Chapter 3: Configuring Your Project

• Append the names of externally linkable entities with: You

may optionally type a string that you want used as a suffix to
reference all linkable entities in other source code languages.
• Prompt on parse errors: By default, parsing errors cause a
prompt asking how to handle that error. When prompted during
analysis, you may choose to ignore that error or all future errors.
Turn this option off to disable this prompting feature. If you
turned it off during analysis, but later want to turn error prompting
back on, check it here.
• Display entity names as: Choose whether entity names should
be displayed in Understand 2.0 with the same case as the
source code (original), all uppercase, all lowercase, only the first
letter capitalized, or mixed case.
....................................................................................................
Fortran>Includes The Fortran->Includes category in the Project Configuration dialog
Category (which you open with Project->Configure) allows you to specify
include directories. You can specify multiple directories to search for
include files used in the project.
Include paths are not recursively searched; that is, any
subdirectories will not be searched for include files unless that
subdirectory is explicitly specified in the list of include directories.
To add a directory, click the New button and then the ... button,
browse to the directory, and click OK.
During analysis, the include directories will be searched in the order
that they appear in the dialog. You can click Move Up or Move
Down to change the order in which directories will be searched.
Typically only include files that are not directly related to your project
(such as system-level includes) and that you do not want to analyze
fully are defined here. For project-level includes you want analyzed,
add those include files as source files in the Sources category.
You can import a list of include directories from a text file by clicking
Import and selecting the file. The file must contain one directory
path per line. (In all such imported text files, a # sign in the first
column of a line in the file indicates a comment. Full or relative paths
may be used. Any relative paths are relative to the project file.)
For more information, see C++->Includes Category on page 3–34.
....................................................................................................
Other Fortran For information about the Fortran->Includes->Replacement Text
Categories category, see C++->Includes-> Replacement Text on page 3–36.
For information about the Fortran->Macros category, see C++-
>Macros Category on page 3–37.

3-42 Understand 2.0 User Guide and Reference Manual

 Java Options

Java Options
In the Java->Options category of the Project Configuration dialog,
you can specify how to analyze Java source code. You see this
window when you choose the Project->Configure Project menu
item and select the Java category.

The Java->Options category contains the following fields:

• Version: Select the version of Java used by the source code in
this project. If you change the version after creating a project, the
project will be reanalyzed when you click OK. The choices are
Java 1.3, 1.4, 5, and 6.
• Prepend the names of JNI/KNI external entities with: You can
specify a prefix used by Java to call functions in other languages.
A Java call to a function “func” would match the C function
prepend_pkg_class_func, where prepend is the string you
specify here, pkg is the Java package name, and class is the
Java class. This follows the Java Native Interface (JNI) and the
Kaffe Native Interface (KNI).
• Save comments associated with entities: You can choose
whether source code comments that occur before and after an
entity should be associated with that entity.

Understand 2.0 User Guide and Reference Manual 3-43

Chapter 3: Configuring Your Project

....................................................................................................
Java->Class Paths The Java->Class Paths category allows you to identify Java .jar
Category and .class files that provide classes for which you do not have
source code.
Both .jar files and .class files are supported. Jar files contain
compressed .java (source) files. Class files contain compiled
sources. By default, the [Link] (or [Link]) file provided by the Java
Developers Kit is located. You can add other .jar files as needed.
To add a directory with .class and .java files, follow these steps:
1 Click Add Path.
2 Locate and select the directory containing .class files.
3 Click OK.

To add a .jar file to the list, follow these steps:

1 Click New Jar.
2 Locate and select the .jar or .zip file. You can select multiple .jar
files while holding down the Ctrl key.
3 Click Open.
If a class is found in both a .java and .class file in the class path, the
class in the .java file is used.
You can import a list of class paths and/or jar files from a text file by
clicking Import and selecting the file. The file must contain one
directory or file path per line. (In all such imported text files, a # sign
in the first column of a line in the file indicates a comment. Full or
relative paths may be used. Any relative paths are relative to the
project file.)

3-44 Understand 2.0 User Guide and Reference Manual

 JOVIAL Options

JOVIAL Options
In the JOVIAL->Options category of the Project Configuration
dialog, you can specify how to analyze JOVIAL source code. You
see this window when you choose the Project->Configure Project
menu item and select the Jovial category.

The Jovial->Options category contains the following fields:

• Version: Select the JOVIAL version you use. JOVIAL73 and
JOVIAL3 are supported.
• Truncate column: By default, statements are not truncated by
column location. You may choose to truncate statements at
column 72 or at some other user-defined column.
• Automatic compool file: Click ... and browse to the compool file
you want to use. The file extension should be .txt.
• Implementation fields: The fields in this section allow you to
specify the sizes and precision of various datatypes. These sizes
vary with different implementations of JOVIAL. You can specify
the number of bits in a byte, number of bits in a pointer, number

Understand 2.0 User Guide and Reference Manual 3-45

Chapter 3: Configuring Your Project

of bits in a word, precision for fixed datatypes, number of bits in a

floating exponent, precision for floating datatypes, and the
precision for an integer.
• Display entity names as: Choose whether entity names should
be displayed in Understand 2.0 with the same case as the
source code (original), all uppercase, all lowercase, only the first
letter capitalized, or mixed case.
....................................................................................................
Jovial->Copy The Jovial->!Copy category in the Project Configuration dialog
Category (which you open with Project->Configure) lets you select
directories to be searched for files named in !COPY directives.
To add a directory to the list, follow these steps:
1 Click the New.

2 Click the ... button and browse to the directory you want to add.
3 Click OK.
When a !COPY directive is analyzed, the directories are searched in
the order listed. To change the search order, select a directory and
click Move Up or Move Down.
You can import a list of directories to be searched for files named in
!COPY directives from a text file by clicking Import and selecting the
file. The file must contain one directory path per line. (In all such
imported text files, a # sign in the first column of a line in the file
indicates a comment. Full or relative paths may be used. Any
relative paths are relative to the project file.)

3-46 Understand 2.0 User Guide and Reference Manual

 Pascal Options

Pascal Options
In the Pascal->Options category of the Project Configuration
dialog, you can specify how to analyze Pascal source code. You see
this window when you choose the Project->Configure Project
menu item and select the Pascal category.

The Pascal->Options category contains the following fields:

• Version: Select the version of Pascal used by the source code in
this project. The choices are Compaq, Delphi, and Turbo. Select
Compaq for legacy DEC Pascal projects.
• Allow embedded SQL: Check this box to enable parsing of
embedded SQL statements in your source code.
• Predeclared entities file: Click ... to select a text file (*.txt) that
contains predeclared routines, types, constants, and parameters
used in your source code. Two versions of this file are provided
in the <install_directory>/conf/understand/pascal directory:
[Link] and [Link].
• Case of externally linkable entities: Choose which case
should be used for “exporting” entities in this language that can
be linked to (for example, called as functions) by other
languages. For example, if an entity is declared in this language
as “MYITEM” and you choose “Lowercase” here, other
languages would be expected to call that entity as “myitem”.

Understand 2.0 User Guide and Reference Manual 3-47

Chapter 3: Configuring Your Project

• Display entity names as: Choose whether entity names should

be displayed in Understand 2.0 with the same case as the
source code (original), all uppercase, all lowercase, only the first
letter capitalized, or mixed case.
....................................................................................................
Pascal->Macros The Pascal->Macros category allows you to add support for
Category preprocessor macros in source code. For example, the $IF, $IFDEF,
and $ELSE directives are supported.
The CPU386 and MSWINDOWS macros are predefined for some
types of Pascal/Delphi sources to avoid generating syntax errors
with the standard library.
For more information about the Pascal->Macros category, see
C++->Macros Category on page 3–37.
....................................................................................................
Pascal->Namespaces The Pascal->Namespaces category allows you to add a directory
Category of namespaces to use when locating a unit specified in a USES
statement. A USES statement may refer to a unit without specifying
a namespace. So, directories you add in this category are searched
in the order provided to find units with unspecified namespaces.
For example, in the following statement, Unit1 has a namespace
specified, so only the namespace [Link] is
searched for Unit1. Since Unit2 has no namespace specified, the
namespaces in the Namespaces category will be searched for
Unit2.
uses [Link].Unit1, Unit2;
To add a namespace directory, follow these steps:
1 Click the New button.
2 Click the ... button and browse to a directory. Then click OK.
3 You can click Move Up or Move Down to change the
precedence order in which the standard libraries are checked.
You can import a list of directories to use when locating units from a
text file by clicking Import and selecting the file. The file must
contain one directory path per line. (In all such imported text files, a
# sign in the first column of a line in the file indicates a comment.
Full or relative paths may be used. Any relative paths are relative to
the project file.)

3-48 Understand 2.0 User Guide and Reference Manual

 Pascal Options

....................................................................................................
Pascal->Standard The Pascal->Standard Library Paths category allows you to
Library Paths specify directories that should be searched for standard libraries.
Category Standard library paths are used to find units that are not found in the
project files. Only files that contain the required units are processed.
For example, the following statement causes the standard libraries
to be searched for a unit names System:
Uses System;
The standard libraries are not used when computing project metrics.
To add a directory, follow these steps:
1 Click the New button.
2 Click the ... button and browse to a directory. Then click OK.
3 You can click Move Up or Move Down to change the
precedence order in which the standard libraries are checked.
You can import a list of directories that should be searched for
standard libraries from a text file by clicking Import and selecting
the file. The file must contain one directory path per line.
....................................................................................................
Pascal->Search Paths The Pascal->Search Paths category allows you to specify
Category directories to search. To add a directory, follow these steps:
1 Click the New button.
2 Click the ... button and browse to a directory. Then click OK.
3 You can click Move Up or Move Down to change the
precedence order in which the standard libraries are checked.
You can import a list of directories to search from a text file by
clicking Import and selecting the file. The file must contain one
directory path per line.

Understand 2.0 User Guide and Reference Manual 3-49

Chapter 3: Configuring Your Project

PL/M Options
In the PL/M->Options category of the Project Configuration dialog, you
can specify how to analyze PL/M source code. You see this window
when you choose the Project->Configure Project menu item and se-
lect the PL/M category.

The PL/M->Options category contains the following fields:

• Display entity names as: Choose whether entity names should
be displayed in Understand 2.0 with the same case as the
source code (original), all uppercase, all lowercase, only the first
letter capitalized, or mixed case.
....................................................................................................
PL/M>Includes The PL/M->Includes category in the Project Configuration dialog
Category (which you open with Project->Configure) allows you to specify
include directories. You can specify multiple directories to search for
include files used in the project.
Include paths are not recursively searched; that is, any
subdirectories will not be searched for include files unless that
subdirectory is explicitly specified in the list of include directories.
To add a directory, click the New button and then the ... button,
browse to the directory, and click OK.
During analysis, the include directories will be searched in the order
that they appear in the dialog. You can click Move Up or Move
Down to change the order in which directories will be searched.
Typically only include files that are not directly related to your project
(such as system-level includes) and that you do not want to analyze
fully are defined here. For project-level includes you want analyzed,
add those include files as source files in the Sources category.
You can import a list of include directories from a text file by clicking
Import and selecting the file. The file must contain one directory
path per line. (In all such imported text files, a # sign in the first
column of a line in the file indicates a comment. Full or relative paths
may be used. Any relative paths are relative to the project file.)
For more information, see C++->Includes Category on page 3–34.

3-50 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

Setting General Preferences

Understand 2.0 allows you to control a number
of aspects of its operation using the
Understand Options dialog. To open this
dialog, choose Tools-> Options. This dialog
provides options to set in the categories shown
to the left:
The subsections that follow describe each of
the categories:
• General Category on page 3–52
• User Interface Category on page 3–54
• User Interface->Lists Category on
page 3–55
• User Interface-> Alerts Category on page 3–56
• Key Bindings Category on page 3–57
• TrackBack Category on page 3–58
• Analyze Category on page 3–59
• Configure Category on page 3–59
• Command Window Category on page 3–59
• Portability Category on page 3–60
• Editor Category on page 3–61
• Editor->Advanced Category on page 3–63
• Editor->Styles Category on page 3–65
• Editor->Browse Category on page 3–66

Understand 2.0 User Guide and Reference Manual 3-51

Chapter 3: Configuring Your Project

....................................................................................................
General Category The following options can be controlled from the General category
of the Tools->Options dialog:

• Application font: To change the font used in dialogs and lists in

Understand 2.0, click Change Font and select the font, font
style, and font size you want to use and click OK.
• Show the Splash-Screen on startup: If checked (on by
default), the logo is shown while Understand 2.0 is starting.
• Show the Getting Started dialog on startup: If checked (on by
default), the Getting Started tab (see page 2–5) is shown in the
document area when you start Understand 2.0.
• Save all modified editor windows when application loses
focus: If checked (off by default), then whenever you move to
another application, any editor windows in which you have made
changes have their contents saved automatically.

3-52 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

• Open last project on startup: If checked (off by default), the

most recently opened project is automatically opened when you
start Understand 2.0 with no other project specified. This is a
useful option if you typically work with only one project.
• Use default working directory: If checked (off by default), you
can select an alternate default directory. This will be the starting
place when you are browsing for other directories and the
directory to which relative directory specifications relate. The
default is the directory where your project is saved.
• Allow interactivity during intensive processing: If checked
(on by default), you can interact with Understand 2.0 while it is
performing background processing. Your interactive events are
processed at the interval you specify in milliseconds.
• Reuse window when requesting a similar type of graph from
within window: If checked (on by default), new graphs open in
the same window from which they were opened. This occurs if
you choose to view a similar graph for an item listed in a graph
window.

Understand 2.0 User Guide and Reference Manual 3-53

Chapter 3: Configuring Your Project

....................................................................................................
User Interface The following options can be set from the User Interface category
Category of the Tools->Options dialog:

• Tree row indentation: You can change the amount of

indentation in hierarchical tree displays.
• Use alternating row colors: If checked (off by default), lists and
tables have shading for alternate rows.
• Animate windows/drawers: If checked (on by default), opening
and closing windows and tabbed areas (drawers) is animated.
You can choose a faster or slower speed than the default.

3-54 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

• Show tabs: If checked (the default), tabs are shown at the top of
the document area for each of the windows open in that area.
This includes the Project Assistant, source editor windows,
graphical views, and other windows.
• Dock Window Layouts: Choose which window layout you
would like to use as the default. The Assistant Layout is good
for new users. The Tight Layout is useful if you will be opening
several source files and want plenty of screen space for that. The
Classic Layout is similar to earlier versions. The Multi-monitor
Layout allows you to take advantage of multiple screens if you
have them.
• Title Formats: Choose whether you want filenames in the title
areas of windows, tabs, and selector files to be short names,
long (full path) name, or relative to the project database.
....................................................................................................
User Interface->Lists The following options can be set from the User Interface->Lists
Category category of the Tools->Options dialog:

• Default most recently used list setting: The default is to show

five items in a list of recently used items. You can change that
default for both lists here.
• Recent files most recently use list: To change the number of
recently used files in the File menu, select the Display item and
change the number to display. If you want to omit the recently
used files from the File menu, uncheck this box.

Understand 2.0 User Guide and Reference Manual 3-55

Chapter 3: Configuring Your Project

• Recent projects most recently use list: To change the number

of recently used projects in the File menu, select the Display
item and change the number to display. If you want to omit the
recently used projects from the File menu, uncheck this box.
....................................................................................................
User Interface-> The following options can be set from the User Interface->Alerts
Alerts Category category of the Tools->Options dialog:

• Save on parse: Choose what you want done with changed but
unsaved source files when the database is to be analyzed. The
default is to always prompt you to choose whether to save files.
Alternately, you can choose to automatically save changed files
or to not save changed files.
• Save on command: Choose what you want done with changed
but unsaved source files when a command is to be run. The
default is to always prompt you to choose whether to save files.
Alternately, you can choose to automatically save changed files
or to not save changed files.
• Prompt before closing the current project: If checked (the
default), you are asked whether you want to close the current
project and all associated windows when you attempt to open a
different project.

3-56 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

....................................................................................................
Key Bindings The functions of keys in Understand 2.0 can be customized. The
Category Key Bindings category of the Tools->Options dialog lets you
choose how keys will work in Understand 2.0:

• Keyboard Scheme: This field allows you to choose groups of

keyboard settings that are similar to other applications. The
default settings are those native to Understand 2.0. Other
choices are Visual Studio .NET key bindings and the Emacs
editor key bindings. If you choose a scheme and click OK, that
scheme will be used. If you make a change to one of the
provided schemes, that becomes a “Custom” scheme. You can
click Save As to name and save your key binding scheme.
• Component: Different portions of Understand 2.0 have different
key behaviors. The components are Application (dialogs and
items not otherwise listed), Change, Comparison View, Editor,
Favorites, Find in Files, Find Results, Information Browser,
Project Browser, Replace Preview and User Tools.
To see a full list of all the current key bindings, choose Help->Key
Bindings.
To change the key sequence for an action, follow these steps:
1 In the Component list, choose the portion of Understand 2.0 in
which the action occurs. Some actions occur in several
components, so you may want to change a key binding in all of
those places.
2 In the Actions list, scroll to find the action you want to modify.
3 Put your cursor in the Primary Sequence or Alternate column.

Understand 2.0 User Guide and Reference Manual 3-57

Chapter 3: Configuring Your Project

4 Press the key combination you want to perform that action. Note
that you can’t use normal editing keys like Backspace or Delete
to edit the keys shown in these fields.
5 When you move focus away from a key binding you changed,
you may see a warning message if the key combination you
chose is already used. For example:

6 Click Yes to make the change or No to cancel the change. Use

the Restore Defaults or Cancel button if you make changes you
don’t want to save. Or, you can choose one of the provided
Keyboard Schemes to go back to a default set of key bindings.
....................................................................................................
TrackBack Category The TrackBack category of the Tools->Options dialog allows you
to send files to the separate TrackBack software to be watched for
changes.

By default, TrackBack is installed with Understand 2.0 and

integration is enabled. To have all of the files in this Understand 2.0
project watched for changes, click the Submit button.
For more about TrackBack integration, see page 8–36.

3-58 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

....................................................................................................
Analyze Category The Analyze category of the Tools->Options dialog allows you to
specify options for how the project is analyzed.

• Sound beep on parse completion: By default, a beep notifies

you when the analysis is complete.
• Show standard library files: For languages whose standard
libraries are parsed by Understand 2.0 (such as Ada), if you
check this box the standard library files are shown in the parse
log. By default, this box is not checked, and the parse log is
shorter.
....................................................................................................
Configure Category The following options can be set from the Configure category of the
Tools->Options dialog:

• Use the New Project Wizard when creating new projects:

The check in this box causes the New Project Wizard (page 3–3)
to be used when you choose File->New Project. If you uncheck
this box, you can specify a project database location and
filename and then use the full Project Configuration dialog.
....................................................................................................
Command Window The following option can be set from the Command Window
Category category of the Tools->Options dialog:

This setting controls the font used in the Run a Command dialog to
display output from the commands you issue.

Understand 2.0 User Guide and Reference Manual 3-59

Chapter 3: Configuring Your Project

....................................................................................................
Portability Category The Portability category of the Tools->Options dialog lets you
specify names to use as substitutes for file paths. Named roots are
similar to environment variables.

After you have defined a named root, you can use that name in
other Understand 2.0 dialogs, such as the Project Configuration.
This is useful, for example, if you want to share projects with people
who reference project files over a network using different paths.
To add a named root, click the Add Named Root button. This adds
a new row where you can type a name and a path (or click the folder
icon to browse for the location).
You can uncheck one or more named roots if you want to
temporarily deactivate certain names.
To use a named root, see Setting File Portability on page 3–16.
Note: You cannot change the portability settings for your project if your
project contains any snapshots. Because the portability setting must
be the same for the current database and all the snapshots, you can
only change portability options before creating snapshots or if you
delete all the snapshots.

3-60 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

....................................................................................................
Editor Category The following options can be set from the Editor category of the
Tools->Options dialog:

• Default style: Use the Font pull-down list to select a font for
Source Editor windows. The fonts shown are the fixed-width
fonts available on your system. Select a Size for the Source
Editor text. If you check the Antialias box, the font is smoothed.
• File Mode: Select the type of Encoding to use when saving
source files and the Line Endings character you want used.
Many encoding formats are supported. The “System” encoding
uses the same encoding format defined for your operating
system. You should change these settings only if your other

Understand 2.0 User Guide and Reference Manual 3-61

Chapter 3: Configuring Your Project

applications have problems opening or displaying files created

by Understand 2.0. By default, these settings apply only to new
files you create, including text and CSV files. The previous
format is preserved for existing files. However, if you check the
Convert existing line endings box, files you save are
converted to the format chosen here.
- Windows line-endings are terminated with a combination of a
carriage return (\r) and a newline (\n), also called CR/LF.
- UNIX line-endings are terminated with a newline (\n), also
referred to as a linefeed (LF).
- Classic Macintosh line-endings are terminated with a single
carriage return (CR).
If you check the Convert tabs to spaces box, tabs are changed
to the number of spaces specified in the Width field when you
save the file. Also, if you check the Add newline at end of file if
absent box, a new line character is added to a file that doesn’t
have one when you save the file (checked by default). If you
check the Remove trailing whitespace box, any spaces or tabs
at the end of lines is deleted automatically when a file is saved.
• Caret Line: Check the Highlight Caret Line box if you want the
full line on which your cursor is located to be highlighted. The
default Color is light gray, but you can change that by clicking
the color box and using the Select Color dialog.
• Externally Modified Files: If an open file is changed in some
other program, Understand 2.0 detects this. Choose Always
Prompt if you want to be notified and asked to load that changed
version. Automatically Reload does this without prompting.
Automatically Ignore is dangerous and not recommended.
• Indent: Check the Show Indent Guide box if you want a dotted
line to show where lines should be indented to. By default, the
Insert Spaces Instead of Tabs box is off; turning it on adds
spaces to a source file when you press Tab. Checking the Auto
Indent box causes automatic indentation when you are typing in
the Source Editor. For Width, specify the number of blank
spaces to use when showing tabs.

Indent Guide

3-62 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

• Show Page Guide: Check the Page Guide box to display a line
similar to the Indent Guide at a defined line width (that is, at the
right edge of the code). Set the Column to the character width
you want to see indicated.
• Whitespace: Select whether you want to see indicators about
whitespace characters. A dot indicates a space, and an arrow
indicates a tab. You can choose Invisible (the default), Always
Visible, or Visible after Indent. Check the Show End-of-Line box
to see the characters that force a line break.
• Margins: Check Line Number (on by default) to turn on line
numbering in the source view. Check Bookmark (on by default)
if you want bookmarks (red arrows) shown in the margin next to
line numbers. Check Fold (on by default) to turn on the ability to
“fold” source code entity blocks out of the way.

....................................................................................................
Editor->Advanced You can further customize the code editor’s behavior in the Options
Category dialog. To open this dialog, choose Tools->Options. Expand the
Editor category, and select the Advanced category.

Understand 2.0 User Guide and Reference Manual 3-63

Chapter 3: Configuring Your Project

The following options control how source code looks when you print
it from an editor window:
• Font Size: Choose the size of the source code you want to use
for printing.
• Color Mode: Choose a color mode for printing. The choices are
as follows. Note that colors other than black and white are
printed only if you are using a color printer and the printer driver
is set to print in color.
- “Normal” matches the current display appearance.
- “Invert Light” prints black as white and white as black. This is
useful if you set the background to a dark color and the text to
light colors for your display.
- “Black on White” prints black code on a white background
regardless of the current display appearance.
- “Color on White” prints colored code on a white background
regardless of the current display appearance.
• Wrap Mode: Choose the wrap mode you want to use for
printing. The default is to wrap words to the next line, but you can
choose to truncate lines or wrap at the character level, which
breaks words across lines.
The Auto-complete options provide for auto-completion of keyword
and entities you type in the editor. As you type, words are shown
below your text. You can arrow down through the list and press
Enter to choose a suggestion.

• Enable Auto-complete: This box is checked by default. If you

want to completely disable auto-completion, uncheck this box.
• Automatically suggest matches: If this box is checked (the
default), suggestions automatically appear below your typing. If
you uncheck this box, you can still see and choose from a list of
auto-completion options by pressing Esc while typing.
• Ignore case: If this box is checked (the default), suggestions
include both upper and lowercase versions of the text you are
typing.

3-64 Understand 2.0 User Guide and Reference Manual

 Setting General Preferences

....................................................................................................
Editor->Styles You can customize the colors used in the Source Code Editor in the
Category Options dialog. To open this dialog, choose Tools->Options.
Expand the Editor category, and select the Styles category.
To change a color, click a color square next to an item in the list.
Use the Select Color dialog to choose a new color for that item.

You can change the text foreground (FG) and background (BG)
colors for any item. You can also make the text bold (B), italic (I), or
underlined (U) for any item. To highlight the whole line for an item,
check the EOL box.
By default, the following color codes are used for the source code:
• Dark blue text: Used for language keywords
• Red text: Used for characters and character strings

Understand 2.0 User Guide and Reference Manual 3-65

Chapter 3: Configuring Your Project

• Italic blue text: Used for comments

• Green text: Used for preprocessor statements
• Black text: Used for all other source text and for line numbers
• White background: Used for most source text
• Pink background: Used for inactive lines of code
• Gray background: Used for line numbers
• Yellow background: Used to highlight text in Find Results for
Find in Files
Additional items are available for customization depending on your
source code language. For Delphi, you can customize the colors of
module, routine, and type names. For FORTRAN, you can
customize the colors of block, module, subprogram, and type
names. For Ada, you can customize the colors of package names,
subprogram names, and type names.
To create additional categories, click New. In the User Style dialog,
type a name for the style, select the language to which this style
applies, and type keywords to be highlighted in this style. Separate
the keywords with spaces, line breaks, or tabs. Then click Save.
You can then set the formatting for your new style.
....................................................................................................
Editor->Browse You can control the behavior of Browse Mode (see page 6–4) in the
Category Source Editor. To see this dialog, choose Tools->Options. Expand
the Editor category, and select the Browse category.

• Activate when Control key is pressed: If this box is checked

(on by default), Source Editor windows use Browse Mode if you
are holding down the Ctrl key when pointing at an entity.
• Visit Source: If this box is checked (on by default), clicking an
entity while in Browse Mode causes focus to jump to the
declaration of that entity.
• Update Information Browser: If this box is checked (on by
default), clicking an entity while in Browse Mode causes the Info
Browser to show information about an entity when you click on it.

3-66 Understand 2.0 User Guide and Reference Manual

 Analyzing the Code

Analyzing the Code

Once you configure a project, Understand 2.0 can parse (that is,
analyze) the project. During analysis, the source files are examined
and data is stored in the Understand 2.0 database. After parsing,
the Understand 2.0 database contains lots of data to browse.
When you save or modify the project configuration, a prompt to
analyze the project appears automatically. You can also analyze the
project in the following ways:
Project->Analyze Changed Files: This analyzes all files
that have been changed and all files that depend on those
changed since the last analysis. This is also referred to as
“incremental analysis.” To analyze changed files, you can also left-
click the toolbar icon shown here. (Ctrl+R)
Project->Analyze All Files:
This forces a full analysis of
all project files, whether they
have changed since the last
analysis or not. As a shortcut
for this command, you can
right-click on the icon and
choose Analyze All Files. (Ctrl+Alt+R)
For either command, the status is reported on the Status Line and
the Command Results window appears with a log of the results.

...

Understand 2.0 User Guide and Reference Manual 3-67

Chapter 3: Configuring Your Project

Analyzing a large project can take some time. If you click Cancel
while the project is being analyzed you will see a message that says
this action will leave the project in an incomplete state. You will need
to analyze the project in order to explore it.
If your project results in errors or warning that you did not expect,
you should revisit the categories of the Project Configuration Dialog
on page 3–8 to make sure your project is configured correctly. The
cause of multiple similar errors is often something like not specifying
an include file directory.
When the analysis is complete, the source code for any errors or
warnings may be examined by double-clicking on the message in
the Parse Log window. If you click the pane-divider arrows,
you can see the source code for errors you double-click on in the
Parse Log window.
To save the Parse Log to a text file, right-click on the white
background of the Parse Log and choose Save As. Specify the
location and name of the file you want to save. Or, you can use
Copy to Clipboard to paste the parse log into another application.
If you have parsed the project during this session, you can choose
Window->Last Parse Log command to reopen the log.
To create a snapshot of the project after parsing, click the
Snapshots button in the lower-right corner of the Parse Log. The
Make Scratch Snapshot option is available in “Pro” and “Analyst”
editions of Understand 2.0. The Make Named Snapshot option is
only available in “Analyst” editions.

Tip: A configured project may be analyzed in batch mode using the

command line program “und”. Refer to Using the und Command
Line on page 13–2 for details on using “und”.
See Analyze Category on page 3–59 for options that affect the
project analysis.
You can schedule automatic project analysis. See Scheduled
Activities on page 3–19 for details.

3-68 Understand 2.0 User Guide and Reference Manual

 Converting an Understand 1.4 Project

Converting an Understand 1.4 Project

You can open and convert an Understand 1.4 project to an
Understand 2.0 project. To do so, choose File->Convert 1.4
Project from the menus.

In the Understand 1.4 Project field, click the folder icon to browse
for the database file for your Understand 1.4 project. This file will
have a file extension of .uda, .udc, .udf, .udj, .udv, or .udp,
depending on the programming language used in the project.
In the New Project Name field, type a name for your new project.
The file extension of .udb will be added automatically. This may be
the same name as the old project, but need not be.
In the Create In field, click the folder icon to browse for the directory
in which you want the new project stored. The default is the directory
that contains the Understand 1.4 project.
When you click Convert, you see the Parse Log window for the
project being converted.

Understand 2.0 User Guide and Reference Manual 3-69

Chapter 3: Configuring Your Project

3-70 Understand 2.0 User Guide and Reference Manual

Chapter 4 Exploring Your Codebase
This chapter covers the basic windows in Understand 2.0 and their
options in detail. It also covers operations within the Filter Area and
the Info Browser.
Details on the use and operation of the Entity Locator and Find in
Files for searching for and locating entities are provided in the
chapter Searching Your Source on page 5–1.
Details on the use and operation of the Source Editor is contained
in the chapter Editing Your Source on page 6–1.

This chapter contains the following sections:

Section Page
PLEASE RIGHT CLICK 4–2
Various Windows Explained... 4–3
Project Assistant 4–4
Entity Filter 4–5
Info Browser 4–8
Project Browser 4–14
Exploring a Hierarchy 4–16
Favorites 4–17

Understand 2.0 User Guide and Reference Manual 4-1

Chapter 4: Exploring Your Codebase

PLEASE RIGHT CLICK

Sorry for shouting (by using all caps above). In order to make the
Understand 2.0 interface as quick, tight and elegant as possible, we
have hidden a lot of power beneath your mouse buttons.
The general rule is that anywhere you look you can right-click to do
or learn something.
A second general rule is that right-click reuses windows where it can
and Ctrl + right-click brings up new windows.
So please right-click. There will be no more reminders.

Check out all the stuff

you can learn or do
right-clicking!

Right-click almost
anywhere to bring up
a menu.

Ctrl + right-click
brings up the same men
but actions happen
in a new window.

4-2 Understand 2.0 User Guide and Reference Manual

 Various Windows Explained...

Various Windows Explained...

Understand 2.0’s GUI has a number of tools for locating and
examining entities. This chapter provides a brief list of all these tools
and describes the Entity Filter, Info Browser, and Favorites in more
detail.
The tools available for finding and exploring entities are:
• Project Assistant: Provides links to actions you can perform.
See page 4–4.
• Entity Filter: Provides an alphabetic list of entities of the
selected type. See page 4–5.
• Info Browser: Provides an explorer for entity characteristics and
connections. See page 4–8.
• Project Browser: Lets you browse a hierarchical file list. See
page 4–14.
• Exploring View: Lets you browse a relationship hierarchy. See
page 4–16.
• Favorites: Lets you provide quick links to frequently-used
entities. See page 4–17.
• Entity Locator: Lets you filter all entities in a project in complex
ways. See page 5–3.
• Find in Files: Searches multiple files. See page 5–8.
• Source Editor: Shows source code. See page 6–1.
• Contextual Information Sidebar: Show context information
about the current source editor file. See page 6–9.
• Scope list: Lists the functions or similar constructs in a file. See
page 6–3.
• Architectures: Defines named regions and views of the project.
See Chapter 7.
• Snapshots: Explore the history of an entity. See Chapter 8.
• Graphical Views: Shows connections and structures of entities.
See Chapter 9.
• Reports: Generate reports about entities. See Chapter 10.
• Metrics: Generate statistics about entities. See page 10–23.

Understand 2.0 User Guide and Reference Manual 4-3

Chapter 4: Exploring Your Codebase

Project Assistant
The Project Assistant provides links to useful tools. You can open it
by choosing Project->Project Assistant.

Project Information
The Project Information portion of the Project Assistant tells you
the full path to the project database, the languages supported in this
project, the number of files in the project, and the total lines of code
in the project.
The remaining sections of the Project Assistant link to various tools.
For information about these tools, see the following locations:

Explore
• View Project Files: See page 4–5.
• View Project Functions: See page 4–5.
• Search Project Files: See page 5–8.
• Search Project Entities: See page 5–3.

Architect
• What is an Architecture? See page 7–2.
• Create a Custom Architecture: See page 7–10.
• Browse Architectures: See page 7–3.
• Manage Architectures: See page 7–9.
• Predefined Architectures: See page 7–10.

Snapshots
• What is a Snapshot? See page 8–2.
• Manage Snapshots: See page 8–10.
• Compare Snapshots: See page 8–14.

Project Metrics
• Project Metrics Summary: See page 11–3.
• Project Metrics Browser: See page 11–4.
• Generate Project Metrics: See page 10–23.
• Generate Project Reports: See page 10–2.

4-4 Understand 2.0 User Guide and Reference Manual

 Entity Filter

Entity Filter
The Entity Filter provides a quick list of the selected entity type. You
can filter this list to match a text string.
The options in the Show list depend upon the languages you have
enabled for your project and the types of entities and relationships
found in your project. If your project uses multiple languages, the
language is listed along with the type.

For each of these types, you can quickly find any entity that has
been declared (or used) in the source code.

By default, the entities are sorted in ascending (A to Z) order. You

can reverse the order by clicking the drop-down icon and
choosing Sort Descending.
You can only have one Entity Filter open. If you close the Entity
Filters window, reopen it by choosing Search->Entity Filter.

Understand 2.0 User Guide and Reference Manual 4-5

Chapter 4: Exploring Your Codebase

....................................................................................................
Using the Filter Field In the Filter field, you can type a string to match a set of entities. By
default, the string matches entity names starting from the first
character. So, for example, you can type “y” to list only entities that
contain a Y or y anywhere in the name.
If you want to quickly jump to the point in the list where entities begin
with a particular letter, just click in the list of entities and type a letter.
You can select other ways for the Filter field to work. Click the drop-
down icon and choose Filter Pattern Syntax. The options are:
• Fixed String: This is the default behavior.
• WildCard: With this option selected, you can use * (any
characters) and ? (any single character) wildcards for pattern
matching. See page 5–5 for examples.
• Regular Expression: With this option selected, you can use
UNIX-style regular expressions. See page 5–5 for an overview.
By default, filtering is case-insensitive. You can make it case
sensitive by clicking the drop-down icon and choosing Filter
Case Sensitivity->Case Sensitive.
When you are finished using a filter and want to see all the entities
for the selected type, click the drop-down icon and choose Clear
Filter.
....................................................................................................
Customizing the You can modify how the Entity Filter lists entities as follows:
Display By default, the full entity name is shown in the Entity Filters list and
entities are alphabetized by their full name. This name may include
a class prefix or other language-specific prefix type. To list entities
by their “short”, unprefixed names, click the drop-down icon and
choose Entity Name as->Short Name.
By default, only the name of the file is shown in a Files list in the
Entity Filter. This name does not include the file location. To list files
including their locations, click the drop-down icon and choose File
Name as->Relative Name or File Name as->Long Name.

4-6 Understand 2.0 User Guide and Reference Manual

 Entity Filter

....................................................................................................
Root Filters Notice that there are the filter type names that contain “Root”, as in
Root Calls, Root Callbys, and Root IncludeBys. These “Root”
types show only the top of a given tree. The tops (or bottoms) of
relationship trees are often helpful points to begin exploring code
that is new to you.
• Root Calls: Lists only entities that call others, but are not called
themselves. These are either high-level code (mains), code
called by hardware (interrupt handlers), or dead (unused) code.
• Root CallBys: Lists only entities that are called by others, but
that do not call anybody else. These are low-level routines.
• Root IncludeBys: Lists only files included by others, but not
included themselves. These are “lower” level include files.
• Root Classes: Lists only classes not derived from other classes.
These are candidates for lower level classes, or library classes.
• Root Decls: Lists only the highest level declaring routines. (Ada)
• Root Withs: Lists only program units (packages, tasks,
subprograms) that With other program units, but are not withed
by anybody else. (Ada)

Understand 2.0 User Guide and Reference Manual 4-7

Chapter 4: Exploring Your Codebase

Info Browser
When you click on an
item in the Entity Filter or
in a number of other
windows, the Info
Browser updates to show
everything that
Understand 2.0 knows
about that entity. The Info
Browser shows this data
as a tree whose branches
can be expanded
individually or all at once.
If the Info Browser isn’t
open, you can open it by
either clicking on an item
in the Entity Filter or
Project Browser. Or, you
can right-click on an item
anywhere and choose
View Information.
Everything Understand
2.0 knows about an entity
can be learned using the
Info Browser. The
information is shown in a
tree. The tree can be
expanded selectively or
in bulk. Each terminating
item (leaf) of a tree
provides some
information about that
entity.
All information in an Info Browser window can be saved to a text file,
or copied and pasted via standard Windows or X11 copying
functions.

4-8 Understand 2.0 User Guide and Reference Manual

 Info Browser

As you drill down you can change which entity you are learning
about. Each time you change the entity, it is remembered in the Info
Browser history for quick backtracking.

Kind and name of entity

Location or path

Relationship tree

Where used

Statistics for this entity

....................................................................................................
Drilling Down A Drilling down the tree works as expected (mostly). To expand a tree,
Relationship click on the + sign. To close the tree click on the - sign.
Right-clicking brings up
a menu that includes
expand/collapse options.
Expand All provides a
shortcut to expand all
levels of the selected
branch.
To open or close the
entire tree, right-click on
the top item and choose
Expand All or Collapse All.
See Saving and Printing Info Browser Text on page 4–13 for details
on the other options in this right-click menu.

Understand 2.0 User Guide and Reference Manual 4-9

Chapter 4: Exploring Your Codebase

....................................................................................................
Displaying More or If you click the icon next to a bold heading such as Calls,
Less Information Called By or References in the Info Browser (or right-click on the
heading), you’ll see options that let you modify how that entity is
listed. These options include:
• Fullname: If checked, the fully-qualified name of the entity is
shown.
• Parameter: Lists the parameters.
• Reference: Choose “Full” to include the file and line location of
the reference.
• Return Type: Lists the return type.
• Sort: Controls the sort order of the list.
• Type: If checked, the datatype is shown.
• Filename: Controls whether the reference format is short, long,
or relative to the project database.
....................................................................................................
Searching the Info If you click the binocular icon at the top of the Info Browser (or click
Browser in the Info Browser and press Ctrl+F), a Find bar appears at the
bottom of the Info Browser.
Type text in the box and click a forward or backward arrow to find an
occurrence of the string in the Info Browser text. All text is searched,
including node names and items that are currently hidden by
collapsed nodes. If you type a string that does not appear anywhere
in the Info Browser text, the field turns red.

To make the search Case Sensitive or to match only Whole

Words, use the drop-down arrow to select those commands.

4-10 Understand 2.0 User Guide and Reference Manual

 Info Browser

....................................................................................................
Syncing the Info You can have multiple Info Browser windows open if you uncheck
Browser the Sync box. Selecting an entity or choosing View Information
updates the Info Browser that has its Sync box checked.
The File Sync box synchronizes the Info Browser with the file in the
active Source Editor.

....................................................................................................
Visiting Source Code In general, if you double-click on an entity in an informational
window (Info Browser or Entity Filter) the declaration of that entity
will be loaded into the Document Area.

Another way to visit source from any entity you see in Understand
2.0, is the right-click menu. Where appropriate, an entity’s right-click
menu contains an Edit Source menu item. In some cases, there are
separate menus items for Edit Definition and Edit Declaration or
separate menus for other language-specific locations.

Understand 2.0 User Guide and Reference Manual 4-11

Chapter 4: Exploring Your Codebase

....................................................................................................
Visiting References The portion of the Info Browser labeled “References” lists
everywhere the entity is referred to in the analyzed source code:

List of each place

the entity is referred
to in the source code

Line number of reference

Kind of use File containing reference

(right click for its context menu)

Left-click on any reference to visit that location in the source code.

Right-click on the “References” title for the node or the down-arrow
next to the node to choose how to organize the references. Your
choices are the default flat list, and all of your architectures.

....................................................................................................
Viewing Metrics The last node on the Info Browser tree is Metrics. This branch
shows the metrics available for the current entity.
By default, when you switch to another entity in the Info Browser, the
Metrics node is closed automatically. This is because it can take a
long time to update the metrics for each entity in a large project.
If your project is small enough that updating metrics as you switch
between entities does not take a long time, you can right-click on the
Metrics node and choose Allow Pre-expansion. The Metrics node

4-12 Understand 2.0 User Guide and Reference Manual

 Info Browser

will then stay open when you change entities. You see the following
warning about the time required for metric updates.

See Metrics Reports on page 10–23 for details on metrics.

....................................................................................................
Saving and Printing All text shown in the Info Browser can be copied to the clipboard for
Info Browser Text pasting into another application as unformatted text. Only the
currently expanded branches are pasted. When saving or pasting in
text format, the branches of the tree are represented by indents in
the text.
The right-click menu offers choices to Copy (only the selected line)
and Copy All.
....................................................................................................
Entity History As you explore your code, you can go many places quickly. Often
you want to backtrack to explore a new path. To help you do this,
the Info Browser contains a full history of what is has displayed. The
Info Browser history can be found in the bottom left corner:

Click small arrows to see a full history list

Choose from menu to jump to that point in your exploration.

History arrows.
Click to move
back and forth
in history.
Use the right and left arrows to move back and forward in the history
list. The down-arrows show the whole list.

Understand 2.0 User Guide and Reference Manual 4-13

Chapter 4: Exploring Your Codebase

Project Browser
To open the Project Browser, choose Project->Project Browser
from the menus.

By default, the Project Browser is in the same area as the Entity

Filter (and the Architecture Browser). Use the tabs on the left to
switch between browser tools in this area.
The Project Browser shows the project files in their directory
hierarchy. You can expand and collapse the tree as needed.
Press Ctrl+F to display a search line at the bottom of the Project
Browser.

4-14 Understand 2.0 User Guide and Reference Manual

 Project Browser

The right-click menus for this view offer a number of options. The
options with icons are also available in the toolbar for the Project
Browser.

Show in Info Browser

Use with Find in Files
Open tree all the way
Close tree all the way
Copy full text to clipboard
Copy selected item text to clipboard
Add a file to the project
Remove selected item from project
Open item in Source Editor
Open item with default OS tool
Search for text in Project Browser
Search in reverse direction

For a file, the right-click menu includes additional commands,

including commands to open graphical views, to parse (analyze) this
file only, to compare snapshots of this file, to find uses of the
filename in project files, and to add the file to the Favorites list.
The Add Existing File command lets you browse for and add
source code files to the project.
To use the Remove command, select one or more files and folders
and choose this command. The Confirm Project Modification dialog
lists files that will be deleted from the project if you click Yes.
The Open Externally command opens an operating system
dependent tool for the directory or file. For example, on Windows it
opens a directory using the Windows Explorer. For a file it opens the
default tool for the file extension.
The Incremental Find command opens a Find bar at the bottom of
the Info Browser. Type text in the box and click an arrow to find an
occurrence of the string in the Project Browser text. All text is
searched, including files in folders that are currently closed. If you
type a string that does not appear anywhere in the Project Browser,
the field turns red. See page 4–10 for details on search options.

Understand 2.0 User Guide and Reference Manual 4-15

Chapter 4: Exploring Your Codebase

Exploring a Hierarchy
The Exploring view lets you browse up and down a relationship
hierarchy within your project.

The right-click menu in the Info Browser, Entity Filter, and Project
Browser offers a command to Explore certain types of entities. The
command may be Explore Calls/Callbys or Explore
Includes/Includebys.
If you click on an item in one column, you see its relationships in the
columns on either side. As you choose items to the left or right,
columns resize to show more of the hierarchy. Calls and Includes go
from left to right. Callbys and Includebys go from right to left.
If you double-click an item, a Source Editor window shows the
entity’s definition.
The References area shows the line number of the current
relationship.
If you check the Sync to Information Browser box, then the Info
Browser automatically displays information about any entity you
select in the Exploring window. Holding the Shift key down
temporarily activates this behavior.
If you check the Jump to First Reference box, then the Source
Editor automatically displays the initial reference to any entity you
select in the Exploring window. Holding the Ctrl key down
temporarily activates this behavior.

4-16 Understand 2.0 User Guide and Reference Manual

 Favorites

Favorites
You can mark entities as “Favorites” so that you can quickly access
them as you would web pages in a browser’s Favorites list.
....................................................................................................
Creating a Favorite To mark an entity as a favorite, follow these steps:
1 Right-click on an entity in the Entity Filters area, the Info
Browser, a source view, a graphical view, or anywhere else
entities occur.

2 From the right-click menu, choose Add Favorite. In the Source

Editor, you can choose to add the entity itself (even if the line
number changes later) or the line number. You will see the New
Favorites dialog.

Understand 2.0 User Guide and Reference Manual 4-17

Chapter 4: Exploring Your Codebase

3 You can change the Name to be shown in the Favorites list.

4 In the Create in box you can select an existing favorites folder or
create a new folder. If you don’t select a folder, the favorite will
be at the top level.
5 Check the All project favorite box if you want this favorite to be
available in all projects you create and use.
6 Click OK to create the favorite.
....................................................................................................
Using the Favorites To open your Favorites list, choose Search->Show Favorites from
the menus.

You can do the following in the Favorites area:

• Double-click an item to see its location in the source.
• Right-click an item and choose View Information to view it in the
Info Browser (unless it was saved as an editor location only).
• Use the Edit, New Folder, and Remove icons in the Favorites
toolbar to manage items.

4-18 Understand 2.0 User Guide and Reference Manual

Chapter 5 Searching Your Source
This chapter covers how to use Understand 2.0’s Find in Files and
Entity Locator features to locate thing in your source code.

This chapter contains the following sections:

Section Page
Searching: An Overview 5–2
Entity Locator 5–3
Find in Files 5–8
Finding Windows 5–14

Understand 2.0 User Guide and Reference Manual 5-1

Chapter 5: Searching Your Source

Searching: An Overview
Finding things in large bodies of source code can be difficult,
tedious, and error prone.
Understand 2.0 offers these solutions for finding things:
• Project wide, entity only, searching using the Entity Locator. This
kind of search finds only entities (not strings, or comments, or
non-syntactically declared or used items). See Entity Locator on
page 5–3.
• Project wide, text-based searching using Find in Files. See Find
in Files on page 5–8.
• Single file searching in the Editor. See Searching Source Code
on page 6–7.
• Text-based searching of various browsers. See Searching the
Info Browser on page 4–10 and Project Browser on page 4–14.
Each of these searching methods has advantages and
disadvantages. Together they provide powerful ways to easily find
what you need to find to better understand and modify your code.

5-2 Understand 2.0 User Guide and Reference Manual

 Entity Locator

Entity Locator
Not all entities fall into one of the tab categories shown in the Entity
Filter. You can find and learn more about any entity by using the
Entity Locator, which provides a filterable list of entities in the
database. You can filter by name, by entity type, by where the entity
is declared, within what container the entity is declared, or when the
entity was last modified. You can also use architecture hierarchies
to sort entities.
To open the Entity Locator, choose Search->Entity Locator from
the main menu bar.

As in other windows in Understand 2.0, when you right-click on an

entity anywhere in the Entity Locator, a menu of commands
available for the item appears.
....................................................................................................
Resizing Columns Column widths can be sized to adjust how much of each column is
visible. You can drag the column header divider between two
columns to resize the column to the left. Or, double-click on the
column header divider while the double-headed arrow is displayed
and the field to the left of the divider will be expanded or shrunk to
the maximum size needed to view all items in that column.
....................................................................................................
Long versus Short In the Entity, Declared In and File columns, you can right-click the
Names column header or click the drop-down icon to specify the display
format for entity names and filenames. For entities, you can choose
the short or full name (which includes the name of the compilation
unit). For filenames, you can choose the short, full, or relative path.

Understand 2.0 User Guide and Reference Manual 5-3

Chapter 5: Searching Your Source

....................................................................................................
Column Headers Column headers are tools in the Entity Locator. Left-click them to
sort according to that column. Right-click a column or click the drop-
down icon to see a menu that lets you control how entities are listed,
sorted, and filtered.

The entity list may be sorted by any column. Left-click on the column
header to toggle between sorting in ascending order and
descending order. The default sorting order is in ascending order of
entity names.
....................................................................................................
Choosing Columns Click the large + icon in the upper-right of the Entity Locator to see
the Locator Column Chooser.

The Entity column must always be displayed. You can enable or

disable the other columns.

5-4 Understand 2.0 User Guide and Reference Manual

 Entity Locator

....................................................................................................
Filtering the List The field below each column heading lets you filter the entities
shown by the Entity Locator. The filter can be entered manually or
automatically based on what was right-clicked on.
For example, you may filter by the Kind column by right-clicking on
any item listed in the Kind column and selecting Filter By Selection
from the menu. This filters the list of entities to contain only entities
of the kind you selected. The title bar shows how many entities
match the filter.
Or, you can simply type a filter in one of the fields. To clear a filter,
just delete the text from the field in the column heading.
The following example shows Filter By Selection for an entity Kind:

To filter the Date Modified column, the left drop-down lets you select
a comparison operator ( <, <=, =, >=, > ), and the right drop-down
lets you select a date from a calendar. You can modify the time by
typing. You must select a comparison operator in addition to a date
in order to filter the entities.
Similarly, the metrics columns allow you to filter with a comparison
operator. For example, you can filter the entities to show only those

Understand 2.0 User Guide and Reference Manual 5-5

Chapter 5: Searching Your Source

with a Cyclomatic complexity greater than some value or a

Comment-to-Code ratio less than some value.
Right-click a column or click the drop-down icon to see the context
menu for that column. You can choose for the filter case sensitivity
to be Case Sensitive or Case Insensitive (the default). You can
also choose for the filter pattern matching syntax to use fixed strings
(the default), wildcards, or regular expressions.
• Fixed string: The string you type matches if that exact string is
found anywhere in the column value.
• Wildcard: These are * or ?, where * matches any string of any
length and ? matches a single character. For example, ??ext_io
matches any name having 8 letters and ending in ext_io.
• Regular expression: A powerful and precise way to filter and
manipulate text. You cannot use the Case Sensitive option if
you are using regular expressions.
The following table lists some special characters used in regular
expressions.

Symbol Description Example

^ Match at the beginning of a line only. ^word
Finds lines with word starting in the first
column.
$ Match at end of a line only. word$
Finds lines that end with “word” (no white
space follows word).
\< Match at beginning of word only. \<word
Finds wordless and wordly but not fullword
or awordinthemiddle.
\> Match at end of word only. \<word
Finds keyword and sword but not wordless
or awordinthemiddle.
. A period matches any single [Link]
character. Finds lines containing word, ward, w3rd,
forward, and so on, anywhere on the line.
* Asterisk matches zero or more word*
occurrences of the previous Finds word, wor, work, and so on.
character or expression.
+ Match one or more occurrences of wor+d
the previous character or expression. Finds word, worrd, worrrd, and so on.

5-6 Understand 2.0 User Guide and Reference Manual

 Entity Locator

Symbol Description Example

? Match zero or one occurrences of the wor?d
previous character or expression. Finds word and wod.
[] Match any one of the characters in [AZ ]
brackets but no others. Finds any line that contains A or Z.
[Kk][eE][Nn]
Finds any variation of case when spelling
"Ken" or "KEn" or "keN".
[^ ] Match any character except those [^AZ ]
inside the brackets. Finds any line that does not contain the
letters A or Z.
[-] Match a range of characters. [A..Z]
Finds any line containing letters A through
Z on them but not lower case letters
| A vertical bar acts as an OR to word | let+er
combine two alternatives into a single Finds word, leter, letter, lettter, and so on.
expression.
\ Make a regular-expression symbol a \*/$
literal character. Allows searching for *. This example finds
all lines ending in */

A full explanation of regular expressions is beyond the scope of this

manual. UNIX users may refer to the manual page for regex using
the command “man -k regex”. For a comprehensive explanation of
regex expressions we refer you to the book “Mastering Regular
Expressions”, published by O’Reilly and Associates
([Link]/catalog/regex or 1-800-889-8969).

Understand 2.0 User Guide and Reference Manual 5-7

Chapter 5: Searching Your Source

Find in Files
You may search all project files or another selection of files for the
occurrence of a text string or regular expression. Matches are
shown in the Find Results window and can be visited in the source
code by double-clicking on any line in the results.
To open this tool, choose Search->Find in Files from the menu bar,
choose Find in... from any right-click menu, or press F5.

The Find in Files area allows you to search multiple files for the
occurrence of a string. In previous versions, this feature was called
Hyper Grep for its similarity to the UNIX command grep.

5-8 Understand 2.0 User Guide and Reference Manual

 Find in Files

In the Find in Files area, specify a search as follows:

• Find: Type the string for which you want to search. The other
fields control how this search is performed. The drop-down list
lets you select from recent Find strings.
• File Types: You can select file extensions for various languages
to narrow the search. Or, type your own file extension pattern.
Leave this field blank to search all files.
• Case Sensitive: Check this box for case-sensitive searching.
The default is to ignore case.
• Match Whole Words: Check this box to match whole words only
(“test” matches “test” but not “testing”). The default is to ignore
word boundaries.
• Search Type: Choose whether to use Fixed String, Wildcard, or
Regular Expression matching. See page 5–6 for details.
• Find In: Choose whether
to search project files
(either all or just the open
files), files in architecture
nodes you select, files in
directories you select, or
files you select.
If you select “Architecture” here, you can click + to browse for an
architecture node. If you select “Directory List” or “File List”, you
can click + to browse for directories or files.
When you right-click on an entity in source code or elsewhere,
the Find In command lets you choose one of these options for
the selected text string. The Find and Find In fields are filled in
for you automatically.
• Semantic Options: If you choose to Find In “Project Files”, you
can check the Only Show Results In box to be able to control
which matches are reported. Then you can check any
combination of the Comments, Strings, Statements, and
Inactive Code boxes to include those types of lines in the
results. You must check at least one of these boxes if you check
the Only Show Results In box.
Click Find after specifying the search criteria. A list of all matching
instances will be displayed in the Find Results window. If the search
is taking a long time and you want to change the criteria, you can
click Stop.

Understand 2.0 User Guide and Reference Manual 5-9

Chapter 5: Searching Your Source

....................................................................................................
Find Results The Find Results window lists the matches found and some
statistics about the results. Each line where the string occurs is
listed in the Results list. The Details section includes the number of
matches, the number of files that contain matches, the number of
files searched, and information about how long the search took.

Multiple searches are shown in the results list. You can right-click on
the background of the window and choose Expand All to expand all
nodes in the window. Or, choose Collapse All to compress the list
to just the top-level search listing.
You can change the organization of the most recent results by using
the Organize Results By drop-down. The choices are a flat list (the
default), a file-based list, and hierarchies using the default
architectures and any custom architectures you have created.
By default, only the name of files is shown. To show full file paths,
select “Long Names” from the Display Files As drop-down.
You can view the source code for a match by double-clicking on a
result. This opens the Source Editor and highlights the match.
From the right-click menu, you can choose Copy or Copy All to
copy the contents of the window as text for pasting elsewhere.
The toolbar (and right-click menu) for the Find Results area lets you
do the following:
Search within the currently selected set of results (using the
same search bar described in Searching the Info Browser on
page 4–10).

5-10 Understand 2.0 User Guide and Reference Manual

 Find in Files

Delete the current set of results.

Delete all the results.
Open the selected match in the Source Editor.
Move to the previous or next match.
You can reopen the Find Results window by choosing Search->
Show Find Results. All the results from the current session are
shown unless you have used the toolbar in the Find Results window
to delete some results.
....................................................................................................
Replace in Files In addition to Find in Files, there is a Replace in Files area you can
open by choosing Search->Replace in Files from the menu bar.

The fields in this area are the same as those in the Find in Files
area. The exception is that there is a Replace field where you type
the text you want to replace the matched string.
When you click Preview Replace, Understand 2.0 checks for any
unsaved source files. If there are unsaved files, you must click Yes
to save all unsaved changes before previewing the changes.

Understand 2.0 User Guide and Reference Manual 5-11

Chapter 5: Searching Your Source

After any files are saved, you see the Preview Replace Changes
window. You can use this window to accept or reject replacements
on a change-by-change basis, file-by-file basis, or all at once. This
window is similar to the comparison areas described in Exploring
Changes on page 8–17.

The top area shows the pre-change code on the left and the post-
change code on the right. Replacements are in pink and the
currently selected replacement is highlighted in blue. The left side
has the Hide Common Lines option set so that most lines that will
not be affected by the replacement are hidden.
The middle area shows the replacements in patch file format. Such
patch files can be used with the Unix patch tool and other similar
programs. You can hide this area by clicking the small
fold icon above the area.
The lower area lists the files where replacements will be made and
the number of replacements accepted and unresolved.
The navigation icons let you move to the next and previous file and
the next and previous replacement.

5-12 Understand 2.0 User Guide and Reference Manual

 Find in Files

The accept and reject icons let you accept or reject replacements on
a change-by-change basis, file-by-file basis, or all at once.

Replacements that you have accepted are marked in the

source display with green circles. Replacements that you
have rejected are marked with red circles. Unresolved
replacements are marked with question marks. You can
click on a green circle to change it to red, and vice versa.
When you have finished resolving differences by either
accepting them or rejecting them, click Perform Replace
Operation. You are asked whether you are sure you want to make
the replacement. The message shows how many replacements will
be made.

If you decide not to make changes, you can click Cancel at any
time. If you have accepted any replacements, you see a message
that asks if you are sure you want to cancel without making
replacements.

Understand 2.0 User Guide and Reference Manual 5-13

Chapter 5: Searching Your Source

Finding Windows
If you have a number of windows open, you can use the options in
the Window menu to organize or find particular windows.
If you have parsed the project during this session, you can use the
Last Parse Log command to reopen the log.
The Change Dock Window Layout lets you choose from several
standard layouts for common tools. The layouts include the “Tight”
layout, “Classic” layout, and “Multi-monitor” layout.
The Window menu also lets you Tile or Cascade the open windows.
You can use Split Vertically or Split Horizontally to split the
document area. When the document area is split, new areas open in
the half that has its box checked. You can drag tabs from one half of
the document area to the other as needed. Choose Window->
Unsplit to remove the split.
The windows you currently have open are listed in the Window
menu. You can select one of these windows to move focus to that
window.
The Window->Navigator command (Ctrl+Tab) opens a temporary
list of currently open windows. When you double-click on an item in
this list, the list goes away and focus is given to the item you chose.
You can dismiss this area without choosing a window by pressing
Esc.

You can reduce the number of windows listed in the Navigator by

choosing a window type from the Show list. Or, you can check the
Type-Ahead Filter box and begin typing some characters in the
name of the window you are looking for. The list of windows is
filtered to match the string you type after checking the box.

5-14 Understand 2.0 User Guide and Reference Manual

 Finding Windows

If you have many windows open in the document area, you can
right-click on the tab for the window you are using and choose
Close All But This or Close All Tabs to the Right.
The Window->Selector command opens an area that lists currently
open windows. Click a window name to make it active. By default,
the Selector lists all windows, but you can choose to show only
Editor windows or various other window types. The icons indicate
the type of window, including whether the source file is unsaved.

You can use the drop-down icon to change the order from
alphabetic to most recently used. Click an item in this list to give that
item focus.
You can type a filter to quickly narrow the list. The current filter is
shown at the bottom of the Selector area.
Using the Selector is a convenient way to perform actions—such as
Close—on multiple windows by selecting multiple windows from the
list, right-clicking, and choosing Close Selected Window(s) or
Close Unselected Window(s).
If you have created bookmarks in your source code (page 6–12),
you can use the Bookmarks command in the Windows menu to
open the list of bookmarks.
You can hide or display categories of toolbar icons by right-clicking
on the toolbar or menu bar and choosing a category. The toolbar is
separated into the following categories: Project, File, Edit,
Configure, Editor History, Favorites, User Tools, TrackBack, Browse,
SplitWorkspace, and Scopes.

Understand 2.0 User Guide and Reference Manual 5-15

Chapter 5: Searching Your Source

5-16 Understand 2.0 User Guide and Reference Manual

Chapter 6 Editing Your Source
This chapter covers Understand 2.0’s source and text file editor.

This chapter contains the following sections:

Section Page
Source Editor 6–2
Saving Source Code 6–6
Searching Source Code 6–7
Other Features 6–10
Printing Source Views 6–14

Understand 2.0 User Guide and Reference Manual 6-1

Chapter 6: Editing Your Source

Source Editor
The Source Editor offers a full featured source code editor, with
syntax coloring and right-click access to information most entities in
your code.

The line numbers and “fold” markings to expand/collapse blocks of

code can be turned on and off in the Editor category of the
Understand Options dialog you can open with the Tools->Options
command (see page 3–61). The display font and a number of other
items can also be changed in the Editor category. You can also
enable bookmarks, indent guide marking, and a right margin marker
(page guide) in that category of the dialog.
The Editor->Styles category of the Understand Options dialog (see
page 3–65) lets you change the colors used for different types of
source code. The Key Bindings category (see page 3–57) shows a
list (and lets you modify the list) of keystrokes you can use in the
Editor.

6-2 Understand 2.0 User Guide and Reference Manual

 Source Editor

....................................................................................................
Scope List You can jump to a particular
function, procedure, or other
language-specific construct in the
current source file by selecting from
the scope drop-down list in the
toolbar. The drop-down list shows
all such constructs found in the file
the last time the project was
analyzed.

You can click the + icon to move the

list to a Scope tab in the area where
the Entity Filter is shown. This tab
lists the constructs in the currently selected source file. This tab is
useful for jumping around in large files.

You can right-click on the Scope List area to choose a sort order
from the right-click menu. The ascending and descending orders
sort alphabetically or reverse alphabetically. The default is file order.

For more power than the scope list, use the Contextual Information
Sidebar on page 6–9.
....................................................................................................
Status Icons Each file in a Source Editor window has a status icon in its upper-left
title bar. The letter inside the icon indicates the type of file. The color
of the icon indicates whether the file has been modified but not yet
analyzed. An asterisk next to the filename marks files with unsaved
changes.

Yellow icon = parsed project file (has not been modified)

Red icon = modified project file (needs to be parsed)
White icon = file not in the project
....................................................................................................
Status Line When a Source Editor is the active window, the status bar at the
bottom of the Understand 2.0 window shows the current line number
and column number, whether the file is in read-write or read-only
mode, and the source language at a quick glance. If TrackBack

Understand 2.0 User Guide and Reference Manual 6-3

Chapter 6: Editing Your Source

integration is enabled, it provides a link to open the TrackBack

history for the file:

If you click the line number in the status bar, you can use the Go To
Line dialog.

If you click the RW (read-write) indicator, it changes the mode to RO

(read-only).
If you click the language, you can choose which language
Understand 2.0 should treat this file as.
....................................................................................................
Selecting and Text can be selected (marked) then cut or copied into the Windows
Copying Text (or X11) clipboard. Selecting text works as standard for the
operating system in use. On Windows, dragging while holding down
the left mouse selects text. Alternately you can hold down the Shift
key and move the cursor (via arrows or the mouse). If you hold
down the Alt key (Ctrl key on X Windows), you can select a
rectangular area of source code—for example, to exclude tabs in
the left margin from the copied text.
Once you select text, you can use the Cut and Copy commands in
the Edit menu or on the right-click menu. You may then paste the
text into other applications as needed.
....................................................................................................
Browse Mode You can switch a Source Editor to “Browse” mode by clicking the
Browse button in the main toolbar. When you are in Browse mode,
the icon is highlighted.

You can temporarily enter Browse Mode by holding down the Ctrl
key while using a Source Editor window.

6-4 Understand 2.0 User Guide and Reference Manual

 Source Editor

In Browse Mode, entities in the code act as links. An underline is

shown when your mouse cursor moves to a link. Clicking a link
moves you to the declaration of that entity and updates the Info
Browser to show details about that entity.
If the declaration of an entity you click on is not found, a message is
shown in the status bar and your computer beeps.
When you are in Browse Mode, you can still edit the file and the
keyboard and right-click function the same as in regular mode. Only
left-clicking the mouse is different.
See page 3–66 for settings to control the behavior of Browse Mode.
....................................................................................................
Right-Click Menu The right-click menu in the Source Editor provides access to a
number of exploration and editing features.
The following exploration features are typically included in the right-
click menu (depending on where you click):
• View Information (see page 4–8)
• Graphical Views (see Chapter 9)
• Edit Source
• Compare with Snapshots (see Chapter 8)
• Explore (see page 4–16)
• Find in... (see page 5–8)
• Add Favorite (see page 4–17)
• Graph Metrics (see page 11–8)
The following editing features are typically included in the right-click
menu:
• Undo / Redo
• Cut / Copy / Paste (see page 6–4)
• Select All
• Hide/Show Inactive Lines (see page 6–10)
• Fold All (see page 6–10)
• Comment Selection / Uncomment Selection (see page 6–10)
• Change Case (see page 6–11)
• Revert (see page 6–6)
• Add Bookmark (see page 6–12)

Understand 2.0 User Guide and Reference Manual 6-5

Chapter 6: Editing Your Source

Saving Source Code

If you have edited a source file, you can click , press Ctrl+S, or
choose File->Save to save your changes.
You can choose File->Save As to save to a different filename. If
you save a project file to another filename, you will be asked
whether you want to add the new file to the project.
If you have edited multiple source files, you can click or choose
File->Save All to save changes to all modified files.
If you want to ignore changes you have made choose since the last
save, right-click in a file and choose Revert.
You can close the current source file by choosing Window->Close
<current_file> from the menus. You can close all source files by
choosing Window->Close All Document Windows. You can also
right-click on the tab for the source file area and choose Close,
Close All But This, or Close All Tabs to the Right.

6-6 Understand 2.0 User Guide and Reference Manual

 Searching Source Code

Searching Source Code

There are a number of ways to search for strings in your source
code or to locate particular lines. The commands for these options
are located in the Search menu. These commands are described in
the locations listed in the following table:

Search Menu Command See

Entity Locator page 5–3
Find in Files page 5–8
Replace in Files page 5–11
Incremental Find page 6–7
Find page 6–8
History page 6–8
Bracket Matching page 6–10
Favorites page 4–17
Contextual Information Sidebar page 6–9
Bookmarks page 6–12

See page 4–3 for a more complete list of the code exploration tools
in Understand 2.0.
....................................................................................................
Incremental Find To search quickly within the current file, press Ctrl+F (or choose
Search->Incremental Find). The status bar of the Source Editor
changes to a search bar.

You can type a string in the field. As you type, matches for that
string are highlighted in the Source Editor. Click Previous or Next to
move from match to match. You can also check the Match Case
and Match Whole Words boxes to modify how the search is
performed.
If you check the Hide box, then as soon as you click on the code,
the incremental search bar is hidden. When you press Ctrl+F again,
your last search is shown. Use Ctrl+Shift+F to find the previous
occurrence.
When the search wraps more than one full time around the file, you
see the icon.

Understand 2.0 User Guide and Reference Manual 6-7

Chapter 6: Editing Your Source

....................................................................................................
Find If you want to use Search-and-Replace or regular expressions for
searching, you can use the Find dialog. To open this dialog, choose
the Search->Find menu item or press Ctrl+Alt+F.

In the Find field, type the string you want to find.

You can check the Regular expression, Match case, and Match
whole words boxes to modify how the search is performed. If you
check the Regular expression box, you can use UNIX-style pattern
matching. For a list of some of the capabilities of regular
expressions, see page 5–5.
If you want to replace the string you are finding, type that in the
Replace field.
Click Previous or Next to search in either direction. Click Replace
All, Replace, or Replace & Find if you want to replace the string
that was found.
The Find dialog searches only individual files. To search multiple
files, see Find in Files on page 5–8.
....................................................................................................
Source Visiting You can move forward or backward through the
History history of your source code visiting locations using
Previous and Next icons in the toolbar. This history
is stored even between Understand 2.0 sessions.
You can click the down-arrows to see the full list of source locations
in the history.
The source locations are stored as line numbers, not by entity
name. If you want to save locations by entity rather than line
number, see Favorites on page 4–17.

6-8 Understand 2.0 User Guide and Reference Manual

 Searching Source Code

....................................................................................................
Contextual The Contextual Information Sidebar (CIS) is similar to the Scope List
Information Sidebar (see page 6–3), but more powerful. You can open the CIS by
choosing Search->Contextual Information Sidebar from the
menus or clicking the icon in the toolbar.

The CIS shows the structure and information for the currently active
Source Editor. The tabs in the CIS provide the following information:
• Structure Browser: This is an expanded scope list for the
current file. It lists the types and names of structures in the file
and highlights the one where your cursor is located. In addition to
functions, it lists includes, macros, classes, and more. Press
Ctrl+F to search within this tab.
• File Information: This tab provides an Info Browser for the
current file.
• Scope Information: This tab provides an Info Browser for the
current entity—that is, the one highlighted in the Structure
Browser tab.
• Context Browser: This tab shows the current entity’s location in
the hierarchy on the left and the entities it contains on the right.
The switch icon (Ctrl+,) to the right of the File Information tab
changes the current file in the Source Editor and the CIS to a file in
the same directory with the same name but a different file extension
(if such a file exists). For example, the switch icon might toggle
between a .c or .cpp file and a .h file with the same name.
As always, right-clicking in any of these tabs provides links to more
information about each entity.

Understand 2.0 User Guide and Reference Manual 6-9

Chapter 6: Editing Your Source

Other Features
The Source Editor also provides several other options for displaying
and editing files.
....................................................................................................
Bracket Matching A handy feature of the Understand editor is syntax bracket
matching. Use this feature to find the matching ending bracket of
syntactically used braces, parenthesis and brackets. Symbols
matched are ( ), { }, and [ ]. Matching isn’t done inside comments.
Pressing Ctrl+j (or right-click and Jump to Matching Brace) jumps
the editor to the matching end or beginning brace. Ctrl+j isn’t active
unless your editing cursor is by a symbol that it can match. Another
Ctrl+j takes you back where you started.
Pressing Ctrl+Shift+J selects all the text from the bracket to its
matching bracket.
Brackets without a match are highlighted in red when you move your
cursor to them. Brackets with a match are highlighted in green.
When your cursor is on a preprocessor directive that has a match
(for example, #ifdef and #endif), you can use Ctrl+j (or right-click
and Jump to Matching Directive) to move your editing cursor to
the match.
....................................................................................................
Folding and Hiding The - and + markings next to the line numbers allow you to “fold” the
code to hide blocks such as functions, if statements, and other
statements that have a beginning and end.

If you right-click on the code, you can choose Fold All to close all
the open blocks.
You can also choose Hide Inactive Lines to hide preprocessor
lines that are not active because a preprocessor macro is not
defined. Choose Show Inactive Lines to view all lines again.
....................................................................................................
Commenting and You can comment code that you have selected by right-clicking and
Uncommenting choosing Comment Selection. To remove the comment characters,
right-click and choose Uncomment Selection.
Note that nested comments within the selection are not parsed.

6-10 Understand 2.0 User Guide and Reference Manual

 Other Features

....................................................................................................
Changing Case You can change the case of selected text in the Source Editor.
Follow these steps:
1 Select a word or words in the source code.
2 Right-click and choose Change Case from the pop-up menu.
3 Choose the type of case you want to apply to the selection. The
choices are as follows:

Choice Default Keystroke Original Result

Upper Case Ctrl+Shift+U Test_me TEST_ME
Lower Case Ctrl+U Test_me test_me
Invert Case Ctrl+Shift+I Test_me tEST_ME
Capitalize Ctrl+Alt+U Test_me Test_Me
....................................................................................................
Keyboard Commands To see a list of keystrokes that work in the Source Editor, choose
Tools->Options and go to the Key Bindings category. For
example, Ctrl+Alt+K cuts the text from the cursor position to the end
of the line. And, Ctrl+T transposes the line at the cursor position with
the line above it.
Another way to see a list of key bindings is to choose Help->Key
Bindings. Search for the line that says “Editor” (around line 110) to
get to the beginning of the keystrokes for the Source Editor
windows.
....................................................................................................
Recording and You can record and replay a set of editing changes that you want to
Replaying Macros be able to repeat. These are called macros.
To record a macro, follow these steps:
1 Choose Tools->Record Macro from the menus or press
Ctrl+Alt+M.
2 Perform the steps you want to be able to repeat.
3 Choose Tools->Record Macro again or press Ctrl+Alt+M.
To replay a macro, move your cursor to the desired start location
and choose Tools->Replay Macro from the menus or press Ctrl+M.
....................................................................................................
Creating and You can use the Source Editor to create an untitled blank file by
Opening Files choosing File->New File from the menus. You can open files,
whether they are in your project or not, by choosing File->Open
File.

Understand 2.0 User Guide and Reference Manual 6-11

Chapter 6: Editing Your Source

....................................................................................................
Bookmarking You can create “bookmarks” in your code by right-clicking on a line
and choosing Add Bookmark from the right-click menu. Lines with
a bookmark have a red arrow next to them.

In a file with multiple bookmarks, you can right-click and choose

Previous Bookmark or Next Bookmark to quickly move between
places in a file.
You can open a Bookmarks area to view a list of all your bookmarks
in all your files by choosing Window->Bookmarks from the menus.

Double-click on a line number listing to move to that bookmark

location in the Source Editor.
If you create a bookmark inside an entity, the Bookmarks area
shows the name and type of entity that contains the bookmark. For
example, the function name is shown if you create the bookmark on
the first line of code inside a function, rather than on the function
declaration line.
The toolbar for this area lets you manage your bookmarks in the
following ways:

You can use the View by icons to switch between

a file-based and a category-based view. The file-base view lets you
expand filenames to see the bookmarks in that file. The category-
based view lets you assign bookmarks to categories you create.

6-12 Understand 2.0 User Guide and Reference Manual

 Other Features

Select a bookmark and click this icon to change the category

the bookmark is in. To create a new category, type the name and
click OK. To use an existing category, select it from the list.

Select a bookmark and click this icon to delete that bookmark.

Select a file in the file-based view and click this icon to delete
all the bookmarks in this file. You can also select a bookmark and
click this icon to delete all the bookmarks in the file that contains the
selected bookmark.

Select a category in the category-based view and click this

icon to delete all the bookmarks in the category. The category itself
is not deleted.

Click this icon to delete all your bookmarks.

....................................................................................................
Managing Source When you right-click on the tab at the top of a Source Editor, some
Editor Tabs of the commands allow you to control the behavior of the tab.

If you choose Show Tab Title as, you can shorten or lengthen the
filename shown in Source Editor tabs. Likewise, if you choose Show
Window Title as, you can shorten or lengthen the filename shown
in the main Understand 2.0 window and any separate Source Editor
windows.
If you choose Release Window, the tabbed area changes to a
separate window that can be moved around your screen. Click
to change a tab to a window within the Understand 2.0 window.

Understand 2.0 User Guide and Reference Manual 6-13

Chapter 6: Editing Your Source

Printing Source Views

The menu option File->Print opens the standard print dialog for
your operating system to send the currently viewed source file to the
printer. The printout will use 66 lines per page.
By default, files are printed in the font and color shown on the
screen when you choose the File->Print menu option.
You can customize code printing in the Options dialog. To open this
dialog, choose Tools->Options. Expand the Editor category, and
select the Advanced category. See Editor->Advanced Category on
page 3–63 for details about these fields.

To change the print output without changing the online display,

choose the File->Page Setup from the menus. This dialog offers
printing options similar to the following; they may differ depending
on your operating system:

6-14 Understand 2.0 User Guide and Reference Manual

Chapter 7 Architecting Your Codebase
This chapter explains the architecture features provided by
Understand 2.0 and explains how you can use them to analyze your
code.

This chapter contains the following sections:

Section Page
About Architectures 7–2
Using the Architecture Browser 7–3
Managing Architectures 7–9
Creating an Architecture 7–10
Building an Architecture 7–13
Using XML to Manage Architectures 7–15
Using Architecture Filters 7–16

Understand 2.0 User Guide and Reference Manual 7-1

Chapter 7: Architecting Your Codebase

About Architectures
An architecture is an abstract hierarchy layered onto a body of
source code. For example, a staff architecture could have nodes for
each engineer working on a particular project. The nodes would
contain a list of source code files belonging to or to be modified by
that engineer. Dependencies and interactions could then be derived
from that architecture.
Architectures allow you to name regions of a software project or
ways of looking at software hierarchically. An architecture creates a
hierarchy of source code units (entities). You can use the provided
architectures or create your own.
Architectures need not reference every source entity in the
database; that is, they can define a subset of the entities. Also,
architectures can contain a particular entity more than once.
(Technically, that is, the architecture's flattened expansion need not
maintain the set property.)
You can combine architectures successively to create novel filters
for your entities.
From a more technical perspective, simple set algebra is used to
combine and transform architecture hierarchies. The result of the
filter is a list of entities. This result list can be viewed as a flat list or
in terms of another architecture. The filter definition can be saved as
a dynamic architecture. A dynamic filter architecture is updated as
the contents of the database change and it can be used to
reconstitute the filter at a later date.
If you have the “Engineer” edition, you can use the auto-
architectures for browsing. If you have the “Pro” edition, you can
also define some Predefined architectures. If you have the “Analyst”
edition, you can also create custom architectures and custom
architecture-based filters.

7-2 Understand 2.0 User Guide and Reference Manual

 Using the Architecture Browser

Using the Architecture Browser

To open the Architecture Browser, choose Architect->Browse
Architectures from the main menubar.

You see an expandable list of the architectures currently defined for

your project.
This Architectures area is similar to the Filters area. When you click
on an item, information about it is automatically shown in the Info
Browser (as long as the “Sync” box is checked in the Info Browser).
....................................................................................................
Exploring To explore the existing architectures, click the “+” signs to expand
Architectures the hierarchy. Entities, such as files, functions, and variables are
shown in the hierarchies.
Understand 2.0 provides some “auto-architectures” that are built in:
• Filesystem: Lists the project files in their normal file hierarchy—
showing directories and their subdirectories.
• Calendar: Lists files in the project according to their last change
date. A hierarchy of dates is shown that progresses from This
Year, This Quarter, This Month, and This Week to Yesterday and
Today.

Understand 2.0 User Guide and Reference Manual 7-3

Chapter 7: Architecting Your Codebase

• Language: Lists files first by their source code language and

then by their location in the filesystem. (This architecture exists
only if your project contains multiple languages.)
The auto-architectures are updated only when the project is
analyzed. So, if your source code is actively being modified and you
have not analyzed it recently, architectures—especially the
Calendar architecture—could be out-of-date.
As always, you can right-click on any item in the Architecture
Browser to get a list of information you can view about that item.

Right-click on file in Architecture Right-click on Architecture node

Notice that the right-click menu for an architecture node (such as a

filesystem directory or “This Quarter” contains some of the following
extra items not available in other right-click menus:
• Graphical Views->Graph Architecture: Creates a graph of the
architecture hierarchy from this point down. You are asked
whether you want to include entities in the graph or just the
architecture nodes. See page 7–6.
• Graphical Views->Dependency Graph: Shows the
dependencies between architecture nodes. See page 7–6.

7-4 Understand 2.0 User Guide and Reference Manual

 Using the Architecture Browser

• Metrics Summary: Provides metrics for the entities within the

selected node. The metrics are based on entities in the current
node, but not those in sub-nodes lower in the hierarchy. See
page 7–7.
• Metrics Export: Creates a CSV output of the metrics from the
Metrics Summary. You can do this only with the “Pro” or
“Analyst” edition. See page 7–7.
• XML Export: Creates an XML export listing the architecture
nodes and entities from the selected point down in the hierarchy.
See page 7–15.
• Edit Architecture: Opens the Architecture Builder for the
selected architecture if it is one you created. You cannot edit the
auto-architectures provided with Understand 2.0. With the
“Analyst” edition, you can edit any other architecture. With the
“Pro” edition, you can edit only the Predefined architectures.
With the “Engineer” edition, you cannot edit architectures. See
page 7–13.
• Rename Architecture: Opens a Rename Architecture window
that lets you rename the selected architecture or node if it is one
you created. You cannot rename the auto-architectures provided
with Understand 2.0. You can rename architectures only with the
“Analyst” edition. See page 7–10.
• Duplicate Architecture: Opens a Duplicate Architecture window
that lets you type a name for a duplicate copy of the selected
architecture. You can duplicate architectures only with the
“Analyst” edition. See page 7–10.
• Manage Architectures: Opens the Architect Manager window.
See page 7–9.

Understand 2.0 User Guide and Reference Manual 7-5

Chapter 7: Architecting Your Codebase

....................................................................................................
Generating Graphs You can generate graphs that show the hierarchy of an architecture.
You can save these graphs as PNG, JPEG, SVG, and Visio files.
To create a graph, follow these steps:
1 Select the highest-level architecture node you want to graph.
You can graph the entire hierarchy or just a sub-hierarchy.
2 Right-click on the node and choose Graphical Views from the
right-click menu. The submenu allows you to choose Graph
Architecture, Dependency Graph, Reverse-Dependency
Graph, or Butterfly-Dependency Graph.
3 In the graph, you can right-click to modify the display. For
example, in the following Architecture Graph, both Include
Entity Lists and Include Referenced Architectures were off by
default but were turned on. Likewise, you can right-click on
Dependency graphs to set options such as the Depth of
expansion levels (default = 1).

4 To save the graph, right-click and select Export to Image File or

Export to Visio File. Export to Image File lets you save to a
JPG, PNG, or SVG file. See page 9–30 for more about these
formats. See page 9–30 for more about Visio files.

7-6 Understand 2.0 User Guide and Reference Manual

 Using the Architecture Browser

....................................................................................................
Generating Metrics You can generate metrics information about an architecture or a
subset of an architecture. The metrics information can be either a
text summary or a comma-separated list for use in spreadsheets.
To create a metrics summary, follow these steps:
1 Select the highest-level node of the architecture for which you
want metrics.
2 Right-click on the node and choose Metrics Summary from the
right-click menu.
3 You see an Architecture Metrics Summary window. For example,
the following two summaries use the Complexity architecture to
compare metrics for “Low Complexity” and “High Complexity”
functions.

4 When you close the window, you are asked whether you want to
save the file. If you click Save, you can save the summary as
text.

Understand 2.0 User Guide and Reference Manual 7-7

Chapter 7: Architecting Your Codebase

To create a metrics export file, follow these steps:

1 Select the highest-level node of the architecture for which you
want metrics.
2 Right-click on the node and choose Metrics Export from the
right-click menu.
3 You see a comma-separated values file. The heading label for
each column is in the first row. Each node in the architecture
hierarchy has a separate row with metrics for that node’s
contents.

4 When you close the window, you are asked whether you want to
save the file. If you click Save, you can save the data as a .CSV
file.

7-8 Understand 2.0 User Guide and Reference Manual

 Managing Architectures

Managing Architectures
To open the Architect Manager window, choose Architect->
Manage Architectures from the main menubar in Understand 2.0.
The window lists the auto-architectures on the right and custom
architectures you have created on the left.

The checkboxes allow you to control whether custom and auto

architectures are shown in the Architectures area. Removing the
checkmark next to an architecture can improve performance,
especially for large projects. So, you might want to disable/hide
architectures you never or rarely use.
You can use the icons at the top of this area or right-click on an
architecture to perform the following actions:
• Create a new architecture: (“Analyst” edition only) See
page 7–10.
• Edit architecture: Predefined and custom architectures
only. (“Pro” and “Analyst” editions only) See page 7–13.
• Rename architecture: Predefined and custom
architectures only. (“Analyst” edition only) See page 7–10.
• Duplicate architecture: (“Analyst” edition only) See
page 7–10.
• Delete architecture: Predefined and custom architectures
only. (“Pro” and “Analyst” editions only)
• Import architecture from XML: See page 7–15.
• Export architecture to XML: See page 7–15.

Understand 2.0 User Guide and Reference Manual 7-9

Chapter 7: Architecting Your Codebase

Creating an Architecture
There are several ways to create a new architecture:
• To create an architecture from scratch, choose Architect->
Create Custom Architecture from the menus or click the
icon in the Architect Manager. Use the Architecture Wizard to
create the architecture as described in Using the Architecture
Wizard on page 7–11.
• To duplicate an existing architecture (which you can then
modify), select an architecture and click the icon in the
Architect Manager window. Or, right-click an existing architecture
node in the Architecture Browser and choose Duplicate
Architecture from the right-click menu to create an architecture
from that node and lower in the hierarchy.

You can rename an architecture you have created by selecting an

architecture and clicking the icon in the Architect Manager
window. Or, right-click on an existing custom architecture and
choose Rename Architecture from the right-click menu.
....................................................................................................
Creating Predefined There are some suggested custom architectures you can create
Architectures using Architect->Predefined Architectures. Choosing any one of
these commands opens the Architecture Wizard.
• Functional Decomposition: Create nodes for code making up
the major components of the project.
• Requirements: Create nodes for code affected by various sub-
projects of a release plan.
• Staff: Create nodes for code handled by each engineer on the
project.

7-10 Understand 2.0 User Guide and Reference Manual

 Creating an Architecture

....................................................................................................
Using the When you open the Architecture Wizard by choosing Architect->
Architecture Wizard New Architecture from the menus or clicking the icon in the
Architect Manager window, you see a page that asks for the name
of your architecture. (If you have the “Pro” edition, you can use the
Architecture Wizard to create the Predefined architectures only.)
Type a name for the architecture. This name should be fairly short
so it can be shown in architecture trees.

Then click Next to see the page that lets you add and edit
architecture nodes. This is the hierarchy to which entities will be
assigned in a later page of the wizard

Understand 2.0 User Guide and Reference Manual 7-11

Chapter 7: Architecting Your Codebase

Click Add a Node and type the Name of the node you want to add.
The default location is within the node you had selected in the
Architecture Wizard, but you can select another location in the
Create In field. Then click OK.

You can modify nodes you have created by selecting a node and
clicking Edit Node. You can delete the selected node by clicking
Remove Node.
The next window presents an animation that shows how to use the
Architecture Builder to add entities to the nodes you have created.
When you have finished watching the animation, click Finish. This
opens the Architecture Builder shown in the animation. Your
architecture nodes are shown on the right. See Building an
Architecture on page 7–13 for details on adding entities to each
node.

7-12 Understand 2.0 User Guide and Reference Manual

 Building an Architecture

Building an Architecture
To edit an existing architecture, select that architecture and click the
icon in the Architect Manager window. Or, right-click on an
existing architecture and choose Edit Architecture from the right-
click menu. Both actions open the Architecture Builder. (If you have
the “Pro” edition, you can use the Architecture Builder to edit the
Predefined architectures only.)
This dialog allows you to add nodes to architectures. You create an
architecture structure on the right-hand side and map entities into
the architecture from the left-hand side.

To create and edit nodes in the Architecture Builder, follow these

steps:
• Double-click the name of any node on the right side of the
Architecture Builder, and rename that node by typing. (Or you
can select a node and press Enter.)
• Move one or more nodes by dragging them to the node you want
to be the parent node. Within a node, the children are sorted
alphabetically.

Understand 2.0 User Guide and Reference Manual 7-13

Chapter 7: Architecting Your Codebase

• Click the icon to create a new node at the same level as the
selected node. Click the icon to create a new node as the
child of the selected node.
• Click the icon to delete the selected node.
• Click the icon to undo your last change. Click the icon
to redo you last undo.
To map files to nodes in the Architecture Builder, follow these steps:
1 On the left side of the Architecture Builder, select an existing
architecture from the drop-down list that will allow you to easily
find the files you want. The default is the Filesystem architecture.
2 You can choose whether to show all entries in the architecture or
just the unmapped entries. For example, if you want to map all
the entries into your new architecture, you might want to select
Show Unmapped Entries so that you can see which files you
haven’t mapped yet.
3 In the left architecture hierarchy, select one or more files or
architecture nodes.
4 In the right architecture hierarchy, select the node you want to
contain your selection.
5 Click the Add button or drag your selection to the right side.
6 When you finish editing your custom architecture, click Save.
You can use the Remove button to delete files and nodes from the
architecture you are editing.
As always, you can right-click on any node or file to use its right-click
menu to get information.
You can save your edits to the architecture at any point by clicking
the icon. Then, you can continue editing. If you close the
Architecture Builder without saving changes, you will be asked if you
want to save your changes.

7-14 Understand 2.0 User Guide and Reference Manual

 Using XML to Manage Architectures

Using XML to Manage Architectures

You can use XML as a way to share architectures between one
Understand 2.0 database and another.
In addition to using XML to share architectures, you can use XML
export/import to quickly create architectures that are a simple subset
of another architecture by selecting a lower node in the hierarchy.
....................................................................................................
Exporting To create an XML file for an architecture, follow these steps:
Architectures to XML 1 Select the highest-level node of the architecture that you want to
export. All of the hierarchy below the node you select will be
represented in the XML file.
2 Click the icon in the Architect Manager window. Or, right-
click on the node you selected and choose XML Export from the
right-click menu.
3 You see an XML file that contains <arch> and <set> tags for
architecture nodes.
4 When you close the XML window, you are asked if you want to
save the file. If you click Save, the default filename is the name
of the node you selected.
....................................................................................................
Importing XML To import an XML file for an architecture, follow these steps:
Architectures 1 Click the icon in the Architect Manager window.
2 In the Choose XML File to Import Architecture dialog, select an
XML file that matches the tag format used by Understand 2.0 to
describe architectures. For example, you can choose XML files
created by Understand 2.0. Click Open.
3 The architecture described by the XML file is added to your list of
architectures.

Understand 2.0 User Guide and Reference Manual 7-15

Chapter 7: Architecting Your Codebase

Using Architecture Filters

Architecture filtering allows you to find a subset of code in which you
are interested.
A powerful way to use architectures is to combine them through
successive filtering. For example, you can use successive filters to
find code that depends upon code that was changed this month. Or,
you can combine custom functional decomposition and staff
architectures to find out who modified entities in the “3Ddisplay”
portion of a project.
Successive filters are saved as dynamic architectures. That is, they
store the parameters used for the filter so that, as the database
changes, the filter continuously updates.

7-16 Understand 2.0 User Guide and Reference Manual

 Using Architecture Filters

To use successive filtering, choose Architect->Filter

Architectures from the menubar in the main Understand 2.0
window. Then, use the Successive Architecture Filter window by
following these steps:
1 Type a Filter Description for the filter you intend to create. This
is a text description—it can be longer than the name you will
save the filter with.
2 Click the “...” button in the row below the Filter Description. You
see a window similar to the following:

3 In the top field, select a defined architecture. For example, in the

figure above, the “Calendar” architecture was selected.
4 In the list of architecture nodes, select the node you want to filter
based on. Then click Save. This places the name of the node
you selected in the first row of the Successive Architecture Filter
window.
5 In the field to the left of the node you
selected, choose how you want the filter
to compare entities. The default is “Is”,
but you can select “Is Not”, “Depends On”
or “Is Depended On By”.
“Depends On” means all the code that the
selected architecture depends upon. For example, if you select
“This Month” and “Is Depended On By”, the result of the filter is
any code that depends upon code that was changed this month.
6 After you have set up one filter line, you can add another line by
clicking the button. Then, fill in the new line by repeating
steps 2 through 5. For lines other than line 1, you can also
choose whether the filters should be ANDed or ORed with the
previous filter. To remove a filter line, click the line’s button.

Understand 2.0 User Guide and Reference Manual 7-17

Chapter 7: Architecting Your Codebase

7 To see the results of your current filter combination, click the

binocular icon.
8 You can change the hierarchy used to display the results of your
filter using the View as Architecture field and clicking the
arrow button.
9 To save your filter combination as a new dynamic architecture,
click the disk icon at the top of the window and enter a name
for the filter.
In contrast to the top save icon button, the lower save
icon saves the results of the filter as a static architecture. The
results of a static architecture are not updated when the
database is updated.
For example, if your filter finds files changed within a certain time
period, those results will be updated with newly changed files
and the new date when you use a dynamic architecture again. In
contrast, a static architecture would save the results as of the
time you created that architecture.

Saves dynamic
architecture

Saves static
results of
architecture
just processed

7-18 Understand 2.0 User Guide and Reference Manual

Chapter 8 Managing Source Changes
This chapter is explains the change-management features provided
by Understand 2.0 and explains how you can use snapshots and the
TrackBack tool to analyze changes to your code.

This chapter contains the following sections:

Section Page
About Snapshots 8–2
Creating Snapshots 8–3
Managing Snapshots 8–10
Comparing Snapshots 8–14
Exploring Changes 8–17
Using Change Reports 8–27
Comparing Entities 8–29
Comparing Files and Folders 8–32
Comparing Text 8–35
Using TrackBack 8–36

Understand 2.0 User Guide and Reference Manual 8-1

Chapter 8: Managing Source Changes

About Snapshots
A snapshot captures the state of the files and entities in your project
at a given point in time. Snapshots allow you to compare changes
between entities as they were at different times.
An Understand 2.0 snapshot stores all the information needed to
regenerate metrics, reports, change markups, and more based on
the state of your source code when you created the snapshot.
(Creating frequent snapshots or snapshots of large code projects
can result in very large .udb project files.)
One advantage of using Understand 2.0 to find differences between
snapshots is that snapshots are always accessible. You don’t need
to do checkouts of old source code in order to make comparisons.
If you want to create snapshots of older generations of your source
code (from before you used Understand 2.0), you can check those
versions out in order to make snapshots of old code, or you can use
TrackBack records to make snapshots of old code.
Unlike the TrackBack tool (see page 8–36), snapshots compare
whole projects at a point in time—not incremental changes to
individual files that are backed up as they happen.
You use the Snapshot Manager to manage snapshots. To open this
window, choose Change->Manage Snapshots from the main
menubar in Understand 2.0.

Note: Once you create a snapshot, you can no longer change the
portability options for your project. Before creating a snapshot, see
page 3–16 to choose a file portability setting.

8-2 Understand 2.0 User Guide and Reference Manual

 Creating Snapshots

Creating Snapshots
To create a snapshot, choose Change->Make Snapshot from the
main menubar in Understand 2.0. (Or, use the icon in the
Snapshot Manager or click the Snapshots button in the Parse Log.)
Choose a type of snapshot to create from the menu. If you have the
“Pro” edition, you can only create a “Scratch” snapshot. If you have
the “Analyst” edition, you can create any type of snapshot.

You can create the following types of snapshots:

• Scratch from Current Database: A snapshot of the source
code in the project. You can rename the snapshot after creating
it. Available with the “Pro” or “Analyst” edition. See page 8–4.
• Named from Current Database: A snapshot of the source code
in the project. You can enter a name, comment, and time for the
snapshot when you create it. Available only with the “Analyst”
edition. See page 8–5.
• Named from Alternate Source Location: A snapshot of a
version of the project source code that is located in another disk
location. For example, you may have checked an older version of
the source code out from a source code control application.
Available only with the “Analyst” edition. See page 8–6.
• Named from Any Point in Time: A snapshot of the project
source code at an earlier point in time using change information
stored by the TrackBack tool. Available only with the “Analyst”
edition. See page 8–9.
You can schedule automatic snapshot creation. See Scheduled
Activities on page 3–19 for details.

Understand 2.0 User Guide and Reference Manual 8-3

Chapter 8: Managing Source Changes

....................................................................................................
Creating Scratch A “Scratch” snapshot is an unnamed snapshot you create of the
Snapshots source code in your project. The default name is “Scratch” and there
can only be one snapshot named “Scratch”. You can rename a
scratch snapshot after creating it.
To create a scratch snapshot, follow these steps:
1 Choose Change->Make Snapshot->Scratch from Current
Database from the main menubar in Understand 2.0.
(Alternately, use the icon in the Snapshot Manager or click
the Snapshots button in the Parse Log.)
2 You will be prompted to parse your project. Click Yes. The
project is parsed and a scratch snapshot is added to the
Snapshot Manager list if it is open. If a snapshot named
“Scratch” already existed, the new snapshot replaces the old
one.
3 If you want to rename this snapshot, select the row for the
Scratch snapshot in the Snapshot Manager and click the
Edit icon.

4 Type a new Snapshot Name. The name may contain spaces,

but should be short enough to fit in table columns and drop-down
fields. Optionally, you can provide a longer Snapshot Comment
to describe this snapshot.

8-4 Understand 2.0 User Guide and Reference Manual

 Creating Snapshots

....................................................................................................
Creating Named A “Named” snapshot is similar to a “Scratch” snapshot except that
Snapshots you can specify the name and comment when you create it. In
addition, you can specify an alternate time for the snapshot—for
example, if you have checked out an older generation of your
source code.
To create a named snapshot, follow these steps:
1 Choose Change->Make Snapshot->Named from Current
Database from the main menubar in Understand 2.0.
(Alternately, use the icon in the Snapshot Manager or click
the Snapshots button in the Parse Log.)
2 You will be prompted to parse your project. Click Yes. The
project is parsed and the Make Named Snapshot dialog opens.

3 Type a Snapshot Name. This should be short enough to fit in

table columns and drop-down fields. If you use a name that is
already in use, you will be asked if you want to replace the
existing snapshot.
4 Optionally, type a longer Snapshot Comment as a description.
5 Optionally, check the Specify Alternate Snapshot Time box
and type a date and time for the snapshot. You can click the
down-arrow to select a date from a calendar.
The default is the current time, and you can keep this default if
you are creating a snapshot of the current state of the codebase.
If you are creating a snapshot of an older version of the
codebase—for example, files that have been retrieved from a
code management system—you may want to modify the date to
match when the files you are snapshotting were created.
6 Click OK. When the snapshot has been created, the new
snapshot is listed in the Snapshot Manager.

Understand 2.0 User Guide and Reference Manual 8-5

Chapter 8: Managing Source Changes

....................................................................................................
Creating Snapshots In addition to creating snapshots of the code in the current project,
from Other Locations you can create snapshots of alternate versions of the source code
that are located in other disk locations. For example, you may have
checked an older version of the source code out from a source code
control application.
To create a named snapshot, follow these steps:
1 Choose Change->Make Snapshot->Named from Alternate
Source Locations from the main menubar in Understand 2.0.
(Alternately, use the icon in the Snapshot Manager or click
the Snapshots button in the Parse Log.)
2 You are prompted to parse your project. Click Yes. The project is
parsed and the Create a Historic Snapshot dialog opens.

3 Type a snapshot Name. This should be short enough to fit in

table columns and drop-down fields.
4 Optionally, type a longer snapshot Comment to describe this
snapshot.
5 Type or choose a Snapshot Date and Time that applies to the
source code of which you are creating a snapshot. You can click
the down-arrow to select a date from a calendar.

8-6 Understand 2.0 User Guide and Reference Manual

 Creating Snapshots

6 Click Add to open the Add Mapping dialog.

7 Click the “...” button next to the Alternate Source path and
browse for the directory where your historic code is located. This
directory should have the same subdirectory structure as a
directory in your Understand 2.0 project. Choosing the highest-
level directory that corresponds to a directory in your project is
best.
8 Click the “...” button next to the Current Project path and
browse for the corresponding directory that already exists in your
project.
9 Click OK.
You can select multiple pairs of current and alternate directory
pairs. All the subdirectories and files that are in the current
project will be replaced in the snapshot by the corresponding
subdirectories and files in the alternate location.
Combined, all the files in your project should be represented in
the alternate location unless they have been added to or deleted
from the project.
10 When you have added all the mappings you want to create, click
OK to create a preview of the snapshot.

Understand 2.0 User Guide and Reference Manual 8-7

Chapter 8: Managing Source Changes

11 Look at the three sections of the Snapshot Preview. This dialog

shows the following:

- Files Found: A count and list of all of the files in the project
path and in the corresponding alternate location you selected.
- Files Not in Current Project: A count and list of source files
that were found in the alternate location but are not part of the
project in its usual location. If the files in the alternate location
are older, these may be files that have since been deleted from
the project. You can uncheck the Include box to exclude these
files from the snapshot.
- Project Files Not in Snapshot: A count and list of source files
that are not in the alternate location but are part of the project.
If the files in the alternate location are older, these may be files
that have been added to the project. Or, the files may be
excluded from the project by filters of various types.
12 If the list of files to be included in the snapshot is correct, click
Yes. Otherwise, click No and attempt to recreate the snapshot
with different paths. When you click Yes, the snapshot is created
and parsed. When parsing is complete, a message says the
snapshot was successfully created.

8-8 Understand 2.0 User Guide and Reference Manual

 Creating Snapshots

....................................................................................................
Creating TrackBack In addition to creating snapshots of the code in the current project,
Snapshots you can create snapshots of code as it was at any point in time as
saved by the TrackBack tool.
To create a TrackBack snapshot, follow these steps:
1 Choose Change->Make Snapshot->Named from Any Point in
Time from the main menubar in Understand 2.0. (Alternately,
use the icon in the Snapshot Manager or click the
Snapshots button in the Parse Log.)
2 You are prompted to parse your project. Click Yes. The project is
parsed and the Make Snapshot From Trackback dialog opens.

3 Type a Snapshot Name. This should be short enough to fit in

table columns and drop-down fields.
4 Optionally, type a longer Snapshot Comment to describe this
snapshot.
5 Type or choose a Snapshot Time to get TrackBack records
from. You can click the down-arrow to select a date from a
calendar.
6 Click OK to create a preview of the snapshot.
7 Look at the three sections of the Snapshot Preview. This dialog
shows the same categories as those described in Creating
Snapshots from Other Locations on page 8–6.
8 If the list of files to be included in the snapshot is correct, click
Yes. Otherwise, click No and attempt to recreate the snapshot
with a different date. When you click Yes, the snapshot is
created and parsed. When parsing is complete, a message says
the snapshot was successfully created. The snapshot date is
listed as the date you selected for use with TrackBack.

Understand 2.0 User Guide and Reference Manual 8-9

Chapter 8: Managing Source Changes

Managing Snapshots
After you have created snapshots, there are a number of ways to
use them. You can rename them, enable them, protect them, purge
them, and compare them.
You perform these actions from the Snapshot Manager, which you
open by choosing Change->Manage Snapshots from the main
menubar in Understand 2.0.

In this window, each snapshot has its own column listing project
metrics for each language used in the project.
Snapshots are sorted from newest to oldest by default. The table
provides some basic metrics about each snapshot. LOC is the total
number of code lines. Comment Ratio is #_of_comment lines /
total_#_of_lines. Avg Complexity is the average number of
independent paths through functions in the project.
In addition to snapshots you have created, the “Latest” snapshot
reflects the current database.
The toolbar for the Snapshot Manager allows you to perform the
following actions:

Icon Description See

Create snapshot page 8–3

Delete selected snapshot page 8–12

Purge unprotected snapshots page 8–13

8-10 Understand 2.0 User Guide and Reference Manual

 Managing Snapshots

Icon Description See

Edit selected snapshot page 8–11

Enable/disable selected snapshot page 8–12

Protect/unprotect selected snapshot page 8–13

Compare snapshots page 8–14

Copy selected snapshot information page 8–13

Copy table of snapshot information page 8–13

Schedule snapshot creation page 3–19

....................................................................................................
Edit Snapshot In the Snapshot Manager, click the Edit icon to open the Edit
Snapshot dialog.

You can modify the name or comment for a snapshot.

Understand 2.0 User Guide and Reference Manual 8-11

Chapter 8: Managing Source Changes

....................................................................................................
Delete Snapshot To delete a snapshot, select one or more rows in the Snapshot
Manager, and click the Delete icon. Click OK if you are sure
you want to delete the snapshot(s).

Removing a snapshot removes information in the Understand 2.0

database. It does not remove the actual files on which the snapshot
is based.
(If removing a snapshot creates enough empty space in the
Understand 2.0 database, the database will be compacted
automatically.)
Snapshots are stored in the project database (.udb file) as a
complete copy of the database information and source code.
Therefore, multiple snapshots, particularly of a large code base, can
make the project database grow quite large.
....................................................................................................
Enable/Disable You can disable snapshots so that they are not visible in the entity
Snapshot comparison described in Comparing the Same Entity Between
Snapshots on page 8–29 and in the snapshot comparison report
described in Using Change Reports on page 8–27.
To disable a snapshot, follow these steps:
1 Open the Snapshot Manager by choosing Change->Manage
Snapshots.
2 Select rows for one or more snapshots you want to hide or
unhide.
3 Click the Enable/Disable icon and select one of the
commands from the drop-down menu. The Enabled column text
for the selected snapshots changes.

8-12 Understand 2.0 User Guide and Reference Manual

 Managing Snapshots

....................................................................................................
Protect/Unprotect You can protect snapshots from being deleted by the Purge
Snapshot command (see page 8–13). This is a good idea for snapshots you
want to keep. You can leave temporary snapshots unprotected and
then easily delete all temporary snapshots to reduce the size of the
project database.
To protect snapshots, follow these steps:
1 Open the Snapshot Manager by choosing Change->Manage
Snapshots.
2 Select rows for one or more snapshots you want to protect or
unprotect.
3 Click the Protect/Unprotect icon and select one of the
commands from the drop-down menu. The Protected column
text for the selected snapshots changes.

....................................................................................................
Purge Snapshots To purge unprotected snapshots (see page 8–13), click the
Purge icon in the Snapshot Manager. You are asked if you really
want to delete all the unprotected snapshots without being able to
undelete them. Click OK to purge.

....................................................................................................
Copy Snapshot If you want to save information about your snapshots in another
Information application, you can copy information from the Snapshot Manager
and paste it into other applications as tab-separated text.
Select one or more rows in the Snapshot Manager and click the
Copy Selection icon. Or, click the Copy Table icon to
get information about all snapshots. Then, paste the information into
another application.

Understand 2.0 User Guide and Reference Manual 8-13

Chapter 8: Managing Source Changes

Comparing Snapshots
To compare snapshots you have taken of your project with the
current state of your project, you can compare snapshots and
explore the differences.
To compare snapshots, follow these steps:
1 Choose Change->Compare Snapshots from the main menubar
in Understand 2.0. This opens the Find Changes dialog
(Alternately, use the icon in the Snapshot Manager. If you
select two snapshots in the Snapshot Manager, these are
automatically chosen as the snapshots to compare.)

2 If you have previously saved comparison settings (see the Save

icon in Changed Entities on page 8–18), you can load them and
use them “as is” or modify them. To do this, click the Load
Parameters button. In the Open Search Settings dialog, select
the settings you want to use and click OK. These settings are

8-14 Understand 2.0 User Guide and Reference Manual

 Comparing Snapshots

copied to the Find Changes dialog, and you can modify them
further if you like.
3 In the “Where” area, choose Everywhere if you want to compare
snapshots of entire projects. To limit the comparison, leave
Choose entities or a set of architectures chosen.
- Click Choose Entity to open the Entity Chooser. Use the
Show field to filter the entity list. You can sort the list by
clicking on the column headings. To hide one or more
columns, click the “+” icon. Find and select one or more
entities whose source code you want to compare. Click the
right arrow to move items to the right list. Then click OK.

- Click Choose Architecture(s) to open the Architecture

Browser. Select one or more architecture nodes to include in
the results. If you select multiple nodes, items in any of the
nodes are compared.

Understand 2.0 User Guide and Reference Manual 8-15

Chapter 8: Managing Source Changes

4 Check the Also search dependents of the above box to

compare entities or architecture nodes that are dependent on the
ones you selected.
5 Check the Also search places that are depended on by the
above box to compare entities or architecture notes that are
depended on by the items you selected.
6 In the Earlier time field of the “When” area, choose the earlier
snapshot to compare. In the results, this snapshot will be shown
on the left.

7 Choose the later snapshot in the Later time field. In the results,
this snapshot will be shown on the right.
If you have the “Pro” edition of Understand 2.0, the Later time
field cannot be changed. It is generally set to the “Current
Database” unless you have created additional snapshots with
the “Analyst” edition and select them in the Snapshot Manager.
8 In the Exclude filter field, type a pattern-matching or regular
expression string to match files you want to exclude from the
comparison. For example, *.c excludes C source files.
9 In the “Options” area, you can choose to do a Case insensitive
comparison or to Skip whitespace. These options are possible
in Understand 2.0 because it compares entities and syntax
rather than comparing files character-by-character as many
differencing tools do.
10 In the “Organize results by” area, check the box if you want to
use an architecture (see Chapter 7) to organize the results. Then
select a Root Architecture from the list. If you don’t check this
box, you won’t be able to use the Tree view in the results.
11 Click Find Changes to compare the snapshots.

8-16 Understand 2.0 User Guide and Reference Manual

 Exploring Changes

Exploring Changes
When you compare snapshots to generate change results, you see
a Change Results area:

Changed Entities
Entity Comparison

Difference List
This area provides several ways to examine the comparison you
created. The results have these main areas:
• Changed Entities: This area lists entities that were changed
using the selected architecture hierarchy. The number of
changes is also provided individually for each source language in
the comparison. See page 8–18.
• Entity Comparison: This area allows you to examine the
differences in entity versions. See page 8–22.
• Patch File: The patch area shows the patch file syntax to
convert from the left version to the right version. See page 8–26.
• Difference List: This area allows you to select individual
differences between two versions. See page 8–26.

Understand 2.0 User Guide and Reference Manual 8-17

Chapter 8: Managing Source Changes

The small fold icon between the areas allows you

to close and reopen areas to make more space for the other
areas. If you point your mouse to the right or left of either fold
icon, you see the pane resize mouse cursor, which allows you
to resize the areas as needed.
....................................................................................................
Changed Entities The Changed Entities portion of the Change Results window lists
entities that were changed. Use the tabs on the left of this area to
switch between a Tree (architecture) view and a flat List view of the
changed entities. (If the Tree view is unavailable, you probably
forgot to check the Organize results by box in the Find Changes
dialog.)

At the top of this area, the two snapshots being compared are listed.
For example, in the figure above, the snapshots are “Oct 1” and
“Current Database” (which is available automatically).
The toolbar near the top of this area contains the following controls:
Save icon: Use this icon to save your comparison settings so
that you can reuse them using the Load Parameters button as
described in Comparing Snapshots on page 8–14. The settings are
stored with your project. When you click the icon, you see the Save

8-18 Understand 2.0 User Guide and Reference Manual

 Exploring Changes

Search Settings dialog, which lists the settings you have already
saved. Type a Name for your settings and click OK.

If you checked the Also search dependents of the above box or

the Also search places that are depended on by the above box
in the comparison settings, you can select the All, Dep. On, and
Dep. On By tabs in the toolbar. If you have made the window
narrow, you may need to use the blue arrows shown here to move
amongst these tabs.

You can filter entities out of the Tree or List view by using the
Exclude checkbox and filter field. Type a pattern matching or
regular expression string and then press the Enter key. For
example, g* and ^g both excludes all entities (such as functions) that
begin with “g”. Note that files that match the filter are not excluded
from tree views because they may contain entities that do not match
the exclude filter.

Reports button: If you have the “Analyst” edition, you

can use this button to generate and view reports based on the
comparison. For details, see Using Change Reports on page 8–27.
Architecture button: Use this button to switch the
Tree view from one architecture to another. By default, the results
are organized according to the Root Architecture field in the File
Changes dialog.

Understand 2.0 User Guide and Reference Manual 8-19

Chapter 8: Managing Source Changes

Colors button: Use this button to change the colors that

indicate material was added, removed, or changed. The default
colors assignments are blue, red, and green, respectively.
When you use the Tree view, expand the architecture to find
changed entities you want to examine. Use the Architecture button
as described previously to change the structure of the Tree view.

When you select an entity, the number and type of changes made to
it are shown to the right in the Change Summary. The Change
Summary area shows how many changes there are within the
selected architecture node or entity. Select a different hierarchy
node or entity to see how many changes there are at each level. If
multiple languages are used within an architecture node, the
Change Summary lists the number of changes for each language.
As always, right-click on any architecture node or entity to see lots of
item-specific options in the right-click menu. When you click on an
entity in the Tree view, information about that entity is shown in the
Info Browser.

8-20 Understand 2.0 User Guide and Reference Manual

 Exploring Changes

When you use the List view, you can select the type of entity to
view using the Show drop-down list. To see the full list, choose All
Entities from the drop-down list.

The List view provides quite a few columns. You can click on the
column headings to sort the list in either ascending or descending
order. Click the icon to open the Locator Column Chooser. By
default, all the columns listed in the dialog are shown if you scroll the
list to the right. You can hide columns to reduce the amount of
scrolling needed if you like.

In the Change Columns area, the Lines Added, Lines Changed, and
Lines Removed columns are available only if you have the “Analyst”
edition. The Change Type, Lines Affected, and New Complexity
columns are available in both the “Analyst” and “Pro” editions.

Understand 2.0 User Guide and Reference Manual 8-21

Chapter 8: Managing Source Changes

If you want to modify the comparison settings, click the New

Comparison button in the Tree view. The Find Changes dialog
opens with the current settings provided. You can modify them and
create a new comparison. Each new comparison is shown in a
separate tab, so you can see multiple comparisons.

You can hide the Changed Entities portion of the results by clicking
the small fold icon below the area. The currently
selected entity remains selected. This makes more space for the
Entity Comparison and Difference List areas.
....................................................................................................
Entity Comparison The Entity Comparison area shows individual differences between
versions of an entity. The display is similar to that of common
differencing tools.

Older snapshot on left Newer snapshot on right

The left side shows the code from the older snapshot of the entity;
the right side shows the code from the newer snapshot. The entity
name and snapshot names are shown just above the code.

8-22 Understand 2.0 User Guide and Reference Manual

 Exploring Changes

Scrolling of the two versions is synchronized horizontally and

vertically. The scrollbar shows the location and size of changed
sections of code using the comparison colors.
For certain languages that Understand 2.0 understands—such
as C code—you can click the + and - signs in the code to
expand and compress code constructs such as if and else
statements, functions, extended comments, and so on.
The currently selected difference is highlighted in blue (or
bluish purple on some screens) by default. Other differences
are highlighted in pink by default.

You can use the small fold icon (like the one shown here)
between the two code versions to hide the older code
temporarily. Or, click the right arrow next to a code change
to do the same thing.
You can edit the source code if you like in the current database
version of the files. You cannot save code directly to a file. Instead,
you can use the button to save a patch file or you can
copy and paste code with merged changes and edits into another
application.
You can select text and copy it to the clipboard. To select text, use
the mouse or your keyboard. To select all, press Ctrl+A or right-click
and choose Select All. To copy text to the clipboard, press Ctrl+C
or right-click and choose Copy.
As always, right-click on any entity name or other text in the code to
see lots of item-specific options in the right-click menu.
To search for text in the source code displayed, follow these steps:
1 Press Ctrl+F to display the Search area in place of the status
bar.

Understand 2.0 User Guide and Reference Manual 8-23

Chapter 8: Managing Source Changes

2 Click on the left or right version to select which one to search.

The default is the right version unless you clicked the left one
more recently.
3 Type the text you want to search for in the search field. The code
automatically moves to the next occurrence of that text as you
type and all occurrences are highlighted. The two versions scroll
together.
4 You can put checkmarks in the Case sensitive or Whole Words
or Hide boxes to specify how the search is performed.
5 Click the Next or Previous arrows to search down or up. If you
want to search the other code version, click there.
The status bar at the bottom of the window shows your line location
in the source code where you last clicked.
The toolbar at the top of the Entity Comparison area contains the
following controls:
Options button: You can use the Options drop-down to
set the following options:

• Options->Case Insensitive: By default, changing the case of a

letter is not treated as a difference. For example, if you change
“a” to “A”, the Difference List shows “No Differences” if that was
the only change.

8-24 Understand 2.0 User Guide and Reference Manual

 Exploring Changes

• Options->Skip Whitespace: By default, changing the number of

spaces or tabs is not treated as a difference. The Difference List
shows “No Differences” if only whitespace was changed. You
can change this behavior by toggling this option off.
• Options->Files are Unicode: By default, differences are
reported only for ASCII files. If Understand 2.0 says “File is
Binary”, use this command to turn on Unicode file handling.
• Options->Hide Common Lines: By default, all lines in both files
are shown. If you check this option, most lines that are the same
in both versions are hidden in the left (older) version.
• Options->Patch lines of context: The patch area shows the
patch file syntax to convert from the left version to the right
version. By default, 3 matching lines are shown around a change
to provide context. You can choose this option and change the
number of lines in the Patch Lines of Context dialog.
• Color choices: These options let you change the highlighting in
the entity comparisons. The Different Word color is an overlay
that is combined with the other highlight colors as appropriate.
• Options->Double Click Merging: A shortcut for merging is to
double-click on a difference in the code. This works only if you
enable it here.
The Case Insensitive, Skip Whitespace, and Files are Unicode
options are not available if you have made a change to a file.
Refresh button: You can use the Refresh button to
update the Difference List at the bottom of the Change Results. This
list may become out-of-date if you merge changes or edit the file
directly.
Save Patch button: You can use the Save Patch
button to create a patch file in “unified format” (or unidiff). This patch
file can be used with the Unix patch tool and other similar programs.
The toolbar at the bottom of the Entity Comparison area contains
the following controls:
Click the Prev and Next buttons below the
Entity Comparison area to jump to another
difference between the entities.
You can merge changes
made in older versions into
the most recent version of an entity. (You cannot merge changes
into an older version.) You cannot save code directly to a file.
Instead, you can save a patch file or copy and paste code with

Understand 2.0 User Guide and Reference Manual 8-25

Chapter 8: Managing Source Changes

merged changes and edits into another application. To merge

changes, follow these steps:
1 Select a difference in the code or by selecting a line in the
Difference List area.
2 Click the Merge Selected button. This copies the older (left)
version of this difference to the current (right) version of the
code. (If you change your mind, click Unmerge Selected.)
3 Click the Prev or Next button to move to another difference and
repeat the previous step.
In the Difference List, merged differences are shown in blue italics.
In the code, differences you have merged are highlighted in green.
(The currently selected difference is still highlighted in blue/purple,
even if it has been merged.)
A shortcut for merging is to double-click on a difference in the code if
you have enabled Double Click Merging in the Options drop-down.
If you know you want to merge all of
the differences, click Merge All. If you
want to undo all merges you have made, click Unmerge All.
....................................................................................................
Patch File This area shows the differences in patch file format. Such patch files
can be used with the Unix patch tool and other similar programs.
You can hide this area by clicking the small fold icon
above the area.
The Patch lines of context command in the Options button menu
lets you adjust the number of unchanged lines shown around a
difference.
....................................................................................................
Difference List The Difference List area shows a list of the changes in the entity
currently shown in the Entity Comparison area.

In the Difference List, merged differences are shown in blue italics.

You can hide the Difference List portion of the results by clicking the
small fold icon below the area. This makes more space
for the Entity Comparison area.

8-26 Understand 2.0 User Guide and Reference Manual

 Using Change Reports

Using Change Reports

You can generate HTML reports that are equivalent to the change
results available in the Change Results window. Many pages are
created, so you can browse the results in various ways.
To generate a report, follow these steps:
1 In the Change Results area, click the button and
choose Generate Report from the drop-down menu.

2 In the Report Name dialog, type a name for your report. This
name is used in the title bar and first page heading of the report.

3 In the Browse For Folder dialog, browse to the location where

you want to store your report.

Understand 2.0 User Guide and Reference Manual 8-27

Chapter 8: Managing Source Changes

4 Unless you already have an empty folder to contain your report,

click Make New Folder, since the report is stored as many files.
Rename the new subfolder to the name you want. Then click
OK.
5 Dialogs show the progress of the report generation. When report
generation is complete, you can click Yes to view the report. To
view it later, click the button and choose View
Report from the drop-down menu. You can also open reports
from the Change->View Reports command in the main menus.

- The Summary shows metrics for all enabled snapshots and

the current version of the project.
- The “Browse changes from all sources” shows changes using
the selected architecture hierarchy.
- Depending on the languages used in your project, pages for
various types of entities are included. For each entity type,
there is a page listing items added, removed, and changed.
- When you click “Added” or “Changed”, a page showing the
differences for that file or entity is shown.
- If you scroll to the bottom of the left pane, you can open the
alphabetic index of changed files and entities.

8-28 Understand 2.0 User Guide and Reference Manual

 Comparing Entities

Comparing Entities
There are two ways to compare entities in Understand 2.0. You can
compare an entity across different snapshots, or you can compare
one entity with another.
....................................................................................................
Comparing the Same When you right-click on an entity in Understand 2.0, the right-click
Entity Between menu often contains the Compare command. When you choose
Snapshots this command, you see the following question (unless you are
comparing an entire file):

• If you choose Quick, whatever is at the entity’s current definition

location in previous snapshots is compared with the entity’s
current definition. For example, if an entity definition is on lines
25 to 35 of the main.c file, then those lines are compared across
snapshots.
• If you choose Slow, then the definitions for the entity in each
snapshot are compared.

Understand 2.0 User Guide and Reference Manual 8-29

Chapter 8: Managing Source Changes

The comparison window looks similar to snapshot comparisons,

except that the top area, the Changed Entities tree or list, is not
shown because you have already selected an entity:

This comparison allows you to select from enabled snapshots

to view the sequence of changes to a particular entity.
Snapshots names are shown above the code. To change a
snapshot version, click the drop-down icon for the left or right code
to see a list of the snapshot versions available. The version you
select on the left must have an earlier date than the version on the
right. Snapshots that you disable (page 8–12) are not listed here.

You can also move backward and forward through the history of a
file’s snapshots by clicking the left and right arrows.
If you are comparing an entity other than a file (such as a function),
merging changes and saving files in the comparison is not
permitted. You can still use the button to create a patch
file in “unified format”.
If you are comparing a file, you can merge changes and use the
Save and Save As buttons for the “Current Database”
version of the file.

8-30 Understand 2.0 User Guide and Reference Manual

 Comparing Entities

....................................................................................................
Comparing Two You can compare two entities by choosing Change->Compare
Entities Entities from the menus. You see the Comparison window.

The middle and lower parts of this comparison behaves similarly to

other comparisons. At the top of the comparison is an entity filter
(page 4–5). Select a type of entity in the Show drop-down. Then
use the lists to select two entities you want to compare.
The Filter fields let you type characters you want to match
anywhere in the entity name. Filtering occurs as you type. Wildcards
and regular expressions are not recognized.
You cannot save merged changes in this comparison. You can use
the button to create a patch file in “unified format”.

Understand 2.0 User Guide and Reference Manual 8-31

Chapter 8: Managing Source Changes

Comparing Files and Folders

Understand 2.0 provides a tool for comparing files and folders. To
open this tool, choose Change->Compare files/folders from the
menus.

You can also launch this tool separately from Understand 2.0 by
running the UndDiff program provided with the Understand 2.0
installation.
In this dialog, select a file or folder for the left and right comparison.
Both sides should be similar files or similar folders. Click the file
button to browse for a file; click the folder button to browse for a
directory.
Subdirectories of the directories you choose are also compared.
When you click Compare, the comparison begins. The status bar at
the bottom of the Understand 2.0 window shows what is being
compared.
The folder and file comparison interface is quite similar to the
Change Results interface. The differences are as follows:
• The comparison uses the following folder and file icons.

Same in both versions

Only in left version
Only in right version
Different in left and right

8-32 Understand 2.0 User Guide and Reference Manual

 Comparing Files and Folders

• By default, all files and folders are

listed. You can use the Show drop-
down to choose whether to restrict the
list to showing only:
- Different: Show files and folders that
either exist in only one version or are
different in the two versions.
- Left Only: Show files that are contained in the left version
only. All different folders are shown because some may
contain files that are only in the left version.
- Right Only: Show files that are contained in the right version
only. All different folders are shown because some may
contain files that are only in the right version.
- Same: Show files that are the same in both versions. All
folders are shown because some that are different may
contain files that are the same.
• The Filter field lets you type characters you want to match in the
directory path or filename. For example, “sim” matches any
folders or files with “sim” in their names. All files within folder that
match the Filter (and the Show drop-down setting) are shown.
Filtering occurs as you type. Wildcards and regular expressions
are not recognized.
• You can change the colors use for folder and file names by
choosing a color from the Colors menu and selecting a new
color in the color picker.

• You can highlight all items that exist in

only the left or right version. To do this,
first right-click on the file list and choose
Expand All. Then click the Select button
and choose either Orphans left or
Orphans right. You will see a warning
that some items may have been skipped; this applies only if you
did not use Expand All.

Understand 2.0 User Guide and Reference Manual 8-33

Chapter 8: Managing Source Changes

• You can copy folders and files from one side to the other. The
copied items overwrite any items with the same names. To copy,
first select the items you want to copy. (To copy a folder and its
contents, select the folder and all the folders and files it
contains.) Then click the Copy/Merge button and choose either
to the right or to the left. This opens the Copy Files dialog,
which lists the files or folders to be copied. If the list is correct,
click OK.

• Unlike the snapshot comparison, you can save changes you

make to files in the file and folder comparison. If you have
modified a file on the right, you can click the Save icon to
save that file to its existing location. You can use the Save
As icon on either the left or right to save a file to a different
location.
• If you have modified a file in the comparison area and then use
the folder and file list to switch to another file, you are asked
whether you want to save the file.
• By default, the file on the left is in read-only mode, and the file on
the right is in read-write mode. You can change the mode for
either file by clicking in the file and then clicking “RO” or “RW” in
the status bar to toggle the mode.

8-34 Understand 2.0 User Guide and Reference Manual

 Comparing Text

Comparing Text
You can compare text that you paste into a window by choosing
Change->Compare arbitrary text from the menus. You see a
window like this:

Paste the before and after text you want to compare into the left and
right sides. Then, click OK to see the comparison.

The text comparison is similar to the comparison between two

snapshots or two entities. You can merge and unmerge changes,
but cannot save files.
Click the fold icon to hide or view the list of differences.

Understand 2.0 User Guide and Reference Manual 8-35

Chapter 8: Managing Source Changes

Using TrackBack
The TrackBack tool automatically tracks changes to files. These
changes are backed up as they happen or on a regular schedule.
By default, TrackBack is installed with Understand 2.0 and
integration is enabled. To change the TrackBack integration setting,
see page 3–58.
TrackBack is a “personal change management” tool that
automatically creates backup versions of important files and
directories. It fills the gap between application-specific “autosave”
functions and expensive enterprise-wide change management
software, providing new power and productivity to individuals.
You can launch TrackBack from within Understand 2.0 by choosing
Tools->TrackBack History Explorer from the menus. For details
about using TrackBack, see the TrackBack User’s Guide.
When a Source Editor window is active, you can use the following
icons in the toolbar for TrackBack integration:
Add the current file to the set of files tracked by TrackBack.
This icon is inactive if the current file is already being tracked.
Open TrackBack to view the history of the current file. This icon
is inactive if the current file is not being tracked by TrackBack. You
can also right-click on a file that is being tracked and choose
TrackBack file history.
When you are in the Source Editor window for a file that is being
tracked by TrackBack, the right end of the status bar shows the
number of revisions of this file stored by TrackBack and you can
click the link to open TrackBack for the current source file.
The first time in a session that you use Understand 2.0 to save a file
that TrackBack is tracking, Understand 2.0 sends the file to
TrackBack for backup when the file is first modified. After the first
save in a session, the settings you have made in TrackBack about
how to monitor the file system for changes are used.

8-36 Understand 2.0 User Guide and Reference Manual

Chapter 9 Using Graphical Views
This chapter covers the graphical views in Understand 2.0 and their
options.

This chapter contains the following sections:

Section Page
Project Overview Graphics 9–2
Graphical View Browsers 9–4
Types of Views 9–10
Graphical Notation 9–18
Controlling Graphics Layout 9–19
Saving Graphical Views 9–30
Printing Graphical Views 9–32

Understand 2.0 User Guide and Reference Manual 9-1

Chapter 9: Using Graphical Views

Project Overview Graphics

You can create graphics that provide an overview of your entire
project by choosing Project->Project Overview Graphs from the
menus. This opens a tab in the document area that contains a
number of pie charts and vertical bar charts. For example:

The graphs provided are code breakdown (line types), function

breakdown, class breakdown, most complex functions, largest non-
file entities, largest files, largest functions, best comment-to-code
ratio entities, and most complex files.

9-2 Understand 2.0 User Guide and Reference Manual

 Project Overview Graphics

In each area, you can choose the Graph View or the Table View.
Both views have a toolbar that lets you save the graph or data.
In the Graph View, you can use the toolbar to:

• Save the image as a PNG, JPEG, or BMP image.

• Copy the image to the clipboard.
• Print the image using the standard Print dialog.
In the Table view, the numeric values for each pie slice or vertical
bar is shown in a table. You can use the toolbar to copy the data to
the clipboard in comma-separated (CSV), tab-separated, or table
format (spaces used so columns align with headings if a font such
as Courier is used).

In addition to the Project Overview Graphs, you can display metrics

graphs that provide additional statistical information about your
project or portions of your project. For details, see page 11–8.

Understand 2.0 User Guide and Reference Manual 9-3

Chapter 9: Using Graphical Views

Graphical View Browsers

The right-click menu of an entity that has a structure or hierarchy
offers a choice called Graphical Views:

You can also use the graphics views drop-down menu in the toolbar
to select from the types of graphs available for the entity at the
current cursor position in a Source Editor tab.

The Graphical Views menu adapts based on what kind of entity

has been right-clicked. A greyed-out item refers to information that is
normally available for this kind of entity but that is not applicable to
this particular entity (for instance a package that could be WITHed
but isn’t).
There are two main types of graphical views: hierarchy views and
structure views.

9-4 Understand 2.0 User Guide and Reference Manual

 Graphical View Browsers

....................................................................................................
Hierarchy Views A hierarchy view shows multiple level relationships between entities.
All relationships are multi-level and are shown to the top or bottom
of their respective tree unless a level option is set in the
preferences. The following is a Call By graph for a function.

....................................................................................................
Structure Views Structure views offer a one glance way to see important structure
and relational information about a given entity. The following is an
example of a Declaration structure view:

Understand 2.0 User Guide and Reference Manual 9-5

Chapter 9: Using Graphical Views

....................................................................................................
General Rules for There are some general rules that can be used for browsing any
Using Graphical type of graphical view.
Browsers • Entity info: Anywhere you see an entity, you can right-click on it
to see a menu that offers many ways to learn more about that
entity. Single-clicking shows information about the entity in the
Info Browser.
• Searching: Click the Search icon at the top of a graphical
view or press Ctrl+F to display the incremental search bar. You
can use this bar that same way you use it in the Source Editor to
find text the current graphical view. As you type search text, all
instances of the string are highlighted in the graphical view. See
page 6–7 for details.

• Opening source: Double-clicking on an entity in a graphical

view opens the source location where the entity is declared.
• Listing open views: You can choose Window->Entity Graphs
from the menus or look at the tabs across the top of the
document area to see a list of all the separate graphical views
you have open.
• Scrolling: You can scroll around a graphical view dragging your
cursor within the view.
• Expanding hierarchy: You can expand and contract tree views
by clicking the red circle to the right of a node. Right-click on the
background of a view and choose Open All Nodes or Close All
Nodes to expand or contract all nodes at once.

Nodes to expand
or contract tree

9-6 Understand 2.0 User Guide and Reference Manual

 Graphical View Browsers

• Path highlighting: To highlight the path for a particular entity in

a tree view (such as a Callby view), select the entity and right-
click. In the pop-up menu, choose Highlight Path.

• Zooming: You can zoom in or out using the toolbar.

• Printing and saving: Everything you see can be printed or

saved. Printing may be done to one page (squeezing the picture)
or across multiple pages (poster style). See Printing Graphical
Views on page 9–32 for details on printing. Graphical views can
be saved as BMP, JPEG, PNG, and Visio files. See Saving
Graphical Views on page 9–30 for details on saving to a graph
file.
• Layout control: Layout is done automatically, there is no need
to move lines or boxes around for a better view. Options are
available for changing the layout. For example, you can control
whether entities are sorted according to their order in the code or
alphabetically. See Controlling Graphics Layout on page 9–19.

Understand 2.0 User Guide and Reference Manual 9-7

Chapter 9: Using Graphical Views

....................................................................................................
Filtering Out Entities You can apply filters to hide certain entities in graphical views. To
create such a filter, follow these steps:
1 Right-click on the background of a graphical view and choose
Edit Graphic Filters from the pop-up menu.

2 In the Graphic Filter dialog, put a checkmark in the Enable

Project Filters box.
3 Click New. This opens the Graphic Filter Editor dialog.

4 Type a filter in the Filter Text field. For example, use gr* to
match entity names beginning with gr. Filters are case-sensitive.
5 In the Filter Criteria field, select whether to compare the filter to
long names, definition files, or the type text of entities. For
example, if you choose long names, a filter of print* does not
match SomeProc::printWide. Instead, you can type *print*.

9-8 Understand 2.0 User Guide and Reference Manual

 Graphical View Browsers

6 In the Action field, select one of the following options:

- Hide Node: Items that match the filter are not included in the
output.
- Hide Sub Nodes: The item that matches the filter is shown,
but any subnodes of these items are removed from the output.
- Collapse Sub Nodes: Any subnodes of items that match the
filter are collapsed in the output. An icon is shown after the
node to indicate that there are subnodes. Items that match the
filter are shown.
7 Click OK to add the filter to the project.
You can also create filters by right-clicking on an entity in a graphical
view and choosing one of the filtering options. The options allow you
to quickly filter out entities with that name or in that file.
You can remove filters you have created by clicking Remove or
Remove All.
The filters you create apply to all graphical views. The status bar
tells how many entities are filtered out of the current view. You can
temporarily disable filtering in the Graphical Settings dialog or by
right-clicking on any graphical view and choosing Disable Graphic
Filters from the pop-up menu.
....................................................................................................
Reuse Checkbox The Reuse checkbox controls whether a view is reused or a new
window is opened when another graphical view is requested. The
Reuse box is unchecked by default. At most one graphical view can
have the Reuse box checked at any time.
However, if you request a similar type of graphical view from within a
graphical view, that view is reused unless you press Ctrl, no matter
whether the Reuse box is checked. You can change this behavior in
the General Category of the Tools->Options dialog (page 3–52).
....................................................................................................
Sync Checkbox The Sync checkbox controls whether this graphical view changes
when a different entity is selected in the Project Browser, Entity
Filter, and other windows that let you select an entity. For example,
if you check the Sync box in a Declaration graph window and then
select a different entity in the Entity Filter, the graph shows
declaration information for the newly selected entity.

Understand 2.0 User Guide and Reference Manual 9-9

Chapter 9: Using Graphical Views

Types of Views
There are two main types of graphical views: hierarchy views and
structure views.
....................................................................................................
Hierarchy View Types Hierarchical views show multi-level relationships between entities.
Understand 2.0 offers hierarchy graphs of the following types of
relationships. Some types apply to specific source languages.
• Butterfly: Shows both calls and called by.
• Calls: Shows who this entity calls.
• Called By: Shows who calls a given entity.
• Include: Shows who this file includes.
• IncludeBy: Shows who includes this file.
• Dependency Graph, Reverse-Dependency Graph, and
Butterfly-Dependency Graph: Available for architectures only.
See page 7–6.
• Derived Classes: Shows classes derived from a given class.
• Base Classes: Show what classes are the base for a class.
• Extends: Shows which classes extend this class.
• Extended By: Shows which classes are extended by this class.
• Class Inheritance: Shows who inherits from a given class.
• Child Lib Units: Shows the Child Library Units of a given
compilation unit. (Ada 95 only)
• Declared In: Shows the declaration tree from where this
program unit is declared.
• Declaration Tree: Shows the declaration nesting of program
units in a compilation unit.
• Instantiated From: Shows the instantiation tree of a generic
type or compilation unit.
• Instantiations: Shows who instantiates a given generic unit.
• Invocation: Shows what compilation units a unit invokes.
• Parent Lib Unit: Shows the parent lib units of a given entity.
• Type Derived From: Shows tree of types a type is derived from.
• Type Tree: Shows types that derive new types from an entity.

9-10 Understand 2.0 User Guide and Reference Manual

 Types of Views

• With: Shows what compilation unit an entity “Withs” into scope.

• WithBy: Shows what compilation units “Withs” a given entity.
• Uses: Shows which modules use this item.
• Used By: Shows which modules are used by this item.
....................................................................................................
Hierarchy View Hierarchy views show multi-level relationships between entities.
Examples Here are examples of the types of hierarchy views that Understand
2.0 offers.
• Butterfly: Shows both calls and called by relationships if they
exist. The selected entity is outlined in red.

• Calls: Shows the entire chain of calls emanating from this

function. Each line between entities is read as “x calls y”.

Understand 2.0 User Guide and Reference Manual 9-11

Chapter 9: Using Graphical Views

• Called By: Shows what calls an entity. Each line connecting an

entity is read as “x is called by y”. In this example, error is called
by code (and others), which is called by rules (and others). Note
that this view is read from the bottom up or right to left.

• Include: Shows the include hierarchy of an entity, such as a file.

A connecting line is read as “x includes y.” In this example,
align.h includes global.h.

• Include By: Shows the include tree in the other direction. In the
previous example, align.h is included by several files such as
algebra.h.
• Base Classes: For classes, shows the base classes from which
this class is derived from. In this example, class CLInearCurve is
derived from class CCurve, which is derived from class CSurface
and so on.

9-12 Understand 2.0 User Guide and Reference Manual

 Types of Views

• Derived Classes: Shows the classes that are derived from this
class. In this example, class CTexture3d is a base class for
classes CIrradianceCache and others.

• Extends: Shows which classes extend other classes. In this

example, the [Link] class extends the [Link]
class, which extends the [Link] class.

• Extended By: Shows which classes are extended by other

classes. A line is read as “class is extended by class.” In this
example, the [Link] class is extended by a number of
classes, including the [Link] class, which in turn is extended
by the [Link] class.

Understand 2.0 User Guide and Reference Manual 9-13

Chapter 9: Using Graphical Views

....................................................................................................
Structure View Types Structure views offer a one glance way to see important structure
and relational information about a given entity. Understand 2.0
structure views include the following:
• Architecture Graph: Shows the hierarchy of an architecture
node. See page 7–6.
• Declaration: Shows what a structure is composed of. For
example, shows the parameters, return type, and callbys of a
function. For classes, shows what members are provided, who
inherits this class, and who it is based on.
• Parent Declaration: Shows what a structure is composed of.
Shows Calls instead of the Called Bys shown by a Declaration
graph.
• Declaration File: Shows what entities (such as functions, types,
macros, and variables) are defined within a given file.
• Declaration Type: Shows what a type is composed of.
• Class Declaration: Shows the members defining the class and
the parent class
• Data Members: Shows what components a class, struct, or type
contains.
• Control Flow: Shows a flow chart of the function or similar entity
type. Clicking on a node in the graphs jumps to the line of code
referenced.
• Package: Shows what entities are declared in a given package
(body or spec).
• Task: Shows the parameters, invocations, and what
entities/entry points are declared in a task. Also shows what the
task Withs.
• Rename Declaration: Shows what entities are renamed in the
entity.
....................................................................................................
Structure View Structure views quickly show structure and relations.
Examples Understand 2.0 structure views are designed to present essential
information about an entity in a small and concise manner. The
structure diagram is derived from the graphs presented by Booch
and Buhr in their respective books “Software Engineering with Ada”
and “System Design in Ada.” Where needed, symbols and
annotations have been extended or altered to represent new kinds
of information available from Understand 2.0.

9-14 Understand 2.0 User Guide and Reference Manual

 Types of Views

• Declaration: Shows the structure of the entity. For example,

shows the parameters, return type, and callbys of a function.

• Parent Declaration: Similar to a Declaration graph but shows

what the entity calls.

Understand 2.0 User Guide and Reference Manual 9-15

Chapter 9: Using Graphical Views

• Declaration File: Shows the entities declared in the file. Also

shows files included by the file and classes imported by the file.

• Declaration Type: Shows information about a type declaration.

9-16 Understand 2.0 User Guide and Reference Manual

 Types of Views

• Class Declaration: Shows the members defining the class and

the parent class from which it is derived.

• Control Flow: Shows a flow chart of the function or similar entity

type.

Understand 2.0 User Guide and Reference Manual 9-17

Chapter 9: Using Graphical Views

Graphical Notation
The following symbols are used by Understand 2.0 to represent
various language constructs. The symbols vary somewhat
depending upon the type of view.
• Entities such as functions and other program units are shown in
rectangles.
• Files and system-level entities are usually shown in
parallelograms.
• Classes and types are shown in flattened hexagons.
• Macros are usually shown in flattened octagons.
• Objects such as variables are usually shown in slightly rounded
rectangles.
• Unknown or unresolved entities are drawn with dashed outlines
or in gray.
• Other shapes are language-specific.
In Control Flow views, standard flow chart symbols, such as
diamonds for decision points, are used.

9-18 Understand 2.0 User Guide and Reference Manual

 Controlling Graphics Layout

Controlling Graphics Layout

The two main types of graphical view windows, Hierarchy and
Structure, have a variety of configuration options. You can set them
by right-clicking on the background of a graphical view and choosing
the option you want to modify from the pop-up menu.

These options control the layout and drawing of the graphic views
and vary based on the current type of view. The following
subsections describe a number of these options.

Understand 2.0 User Guide and Reference Manual 9-19

Chapter 9: Using Graphical Views

....................................................................................................
Called by Menu The Called by menu controls whether program units that call the
current entity are shown in declaration views.

View with Called By set to On View with Called By set to Off

....................................................................................................
Constants Menu The Constants menu controls whether to show constants in
Declaration views. The default is On.
....................................................................................................
Default Members The Default Members menu controls whether declaration views
Menu show default members of the class.
....................................................................................................
Dependent Of Menu The Dependent Of menu controls whether files a C file is
dependent on are drawn in the C File Declaration view. The Default
is On.
....................................................................................................
Dependent Menu If Dependents is on (the default) then files dependent on the current
C file are shown in a File Declaration view.
....................................................................................................
Duplicate Subtrees The Duplicate Subtrees menu controls whether multiple
Menu occurrences of the same sub-tree are shown in hierarchy views. The
options are to Hide or Show such subtrees. The default is to show
duplicate subtrees. In some applications, hiding duplicate subtrees
can dramatically simplify hierarchy views. Duplicate subtrees are not
shown if a view has over 1000 nodes.
....................................................................................................
Extended By Menu The Extended By menu controls whether declaration views show
classes by which the selected class is extended.

9-20 Understand 2.0 User Guide and Reference Manual

 Controlling Graphics Layout

....................................................................................................
Extends Menu The Extends menu controls whether declaration views show
classes that the selected class extends.
....................................................................................................
External Functions If External Functions is on then functions defined in a header file or
Menu in a file included by a header file are shown in the Declaration View
for a header file. Default is On.
....................................................................................................
Filename Menu The Filename menu controls how filenames are displayed in views.
It is available for both declaration and hierarchy views. The options
are Off and On.:
• None: Filenames are not shown in the view.
• Shortname: Where filenames are relevant, only the name of the
file is shown in square brackets.
• Fullname: Where filenames are relevant, the full file path and
filename are shown in square brackets.
....................................................................................................
Function Pointer The Function Pointer menu controls whether function pointers are
Menu displayed as invocations in the Call and CallBy trees.

....................................................................................................
Globals Menu The Globals menu controls whether to show globals in Declaration
views. The default is On.
....................................................................................................
Implements Menu The Implements menu controls whether declaration views show
entities that the selected entity implements.
....................................................................................................
Implemented By The Implemented By menu controls whether declaration views
Menu show entities by which the selected entity is implemented.

Understand 2.0 User Guide and Reference Manual 9-21

Chapter 9: Using Graphical Views

....................................................................................................
Imports Menu The Imports menu controls whether declaration views show entities
imported by the current entity.

View with Imports set to On View with Imports set to Off

....................................................................................................
Included By Menu If IncludeBy is on (default) then files that include the Header File
being drawn in a Header File Declaration view are shown.
....................................................................................................
Includes Menu The Includes menu controls if include files are drawn on file
declaration diagrams (C file, Header file). Default is On.
....................................................................................................
Inherits Menu The Inherits menu controls whether declaration views show entities
that the selected entity inherits.
....................................................................................................
Inherited By Menu The Inherited By menu controls whether declaration views show
entities inherited by the selected entity.
....................................................................................................
Intrinsic Menu The Intrinsic menu controls whether intrinsic functions (for
example, cos and sin) are displayed or hidden.

9-22 Understand 2.0 User Guide and Reference Manual

 Controlling Graphics Layout

....................................................................................................
Invocations Menu The Invocations menu controls whether procedures and functions
called by the current procedure or function are shown in Declaration
views.

View shows Invocations View without Invocations shown

....................................................................................................
Layout Menu The Layout menu controls the layout algorithm for a hierarchical
chart. It is available only in hierarchy views (calls, callby, etc.). The
options are:
• Crossing: A left-to-right view, minimizing space used but
sacrificing some readability by permitting lines between entities
to cross.

Understand 2.0 User Guide and Reference Manual 9-23

Chapter 9: Using Graphical Views

• Horizontal Non-Crossing: A left-to-right layout, using more

space in some situations but enhancing readability by having no
crossing lines.

• Vertical Non-Crossing: A top-to-bottom layout similar to

Horizontal Non-Crossing.

....................................................................................................
Level Menu The Level menu controls the number of levels to be traversed when
laying out a hierarchical view. The default value is “All Levels”.
Values of 1 to 5 may be set. It is available only in hierarchy views.

All Levels One Level

....................................................................................................
Locals Menu The Locals menu controls whether local items are shown in
Declaration views. The default is On.

9-24 Understand 2.0 User Guide and Reference Manual

 Controlling Graphics Layout

....................................................................................................
Members Menu The Members menu controls whether members and operators are
shown in the Type Tree and Type Derived From views. The choices
are to show None, Components, Operators, or Operators and
Components.
....................................................................................................
Name Menu The Name menu controls whether or not fullnames are used in
views. It is available for both declaration and hierarchy views.

A fullname includes its parent compilation units. For example:

• Text_Io.Put is the fully specified name.
• Put is the Short Name
Longer versus shorter names can alter the layout of pictures
substantially.
....................................................................................................
Objects Menu The Objects menu controls whether to show objects in Declaration
views. The default is On.
....................................................................................................
Operators Menu The Operators menu controls whether entities that are operators
are shown in the Callby, Declaration, Declaration Tree, and
Invocation views.

Understand 2.0 User Guide and Reference Manual 9-25

Chapter 9: Using Graphical Views

....................................................................................................
Parameters Menu The Parameters menu controls whether parameters are shown in
hierarchical views. Available on any hierarchical graphical view
(invocation and callby). The default is Off, turning this On can make
hierarchical pictures much bigger.

Parameters Off (the default)

Parameters On
....................................................................................................
Private Members The Private Members menu controls whether declaration views
Menu show private members of the entity.
....................................................................................................
Protected Members The Protected Members menu controls whether declaration views
Menu show protected members of the entity.

....................................................................................................
Public Members The Public Members menu controls whether declaration views
Menu show public members of the entity.
....................................................................................................
Renames Menu The Renames menu controls whether declarations that are
renames are shown in Declaration views. The default is to show
rename declarations.
....................................................................................................
Routines Menu The Routines menu controls whether to show routines (procedures,
functions, ...) in Declaration views. The default is On.

9-26 Understand 2.0 User Guide and Reference Manual

 Controlling Graphics Layout

....................................................................................................
Scale Menu The Scale menu allows you to choose the size of the text used. It is
available for both declaration and hierarchy views. All picture sizes
and layouts vary with text point size. The currently selected size is
indicated by a check mark.

Other point sizes can be added by customizing configuration files

found in the Understand 2.0 installation directory. Contact
support@[Link] for information on how to do this.
....................................................................................................
Sort Menu The Sort menu lets you specify whether entity names in tree views
should be sorted alphabetically. If this option is off (the default),
entities are sorted in the order they are encountered in the project.
....................................................................................................
Spacing Menu The Spacing menu lets you choose to change the space between
boxes. You can choose compact, small, normal, wide, or extra wide.
....................................................................................................
Sql Menu The Sql menu lets you specify whether SQL entities should be
shown in graphical views. This option is on by default.
....................................................................................................
Static Menu The Static menu controls if static functions are drawn in function, C
File and Header File declaration views. Static functions are those
declared using the “static” keyword. They are visible only within the
file they are declared in. If enabled static functions are drawn with
the edge of their box inside the edge of the outer declaration box for
their enclosing unit (C file). Default is On.

Understand 2.0 User Guide and Reference Manual 9-27

Chapter 9: Using Graphical Views

....................................................................................................
Text Menu The Text menu sets the way entity names are trimmed or altered to
accommodate the layout of graphics. It is available for both
declaration and hierarchy views. Names may be truncated to a
certain length or wrapped at a certain length.

• No Truncation: Uses the name as defined in the source code.

The default.
• Truncate Short: Cuts off names at 10 characters.
• Truncate Medium: Cuts off names at 20 characters.
• Truncate Long: Cuts off names at 30 characters.
• No Wrap: Never wraps text to the next line.
• Wrap Short: Wraps the name between 8 and 10 characters.
Location in that range depends on if a natural wrapping character
is found. Natural wrapping characters are . _ - and :
• Wrap Medium: Similar to Wrap Short except wrapping range is
15-20 characters.
• Wrap Long: Similar to Wrap Short except wrapping range is 20-
30 characters.
....................................................................................................
Types Menu The Types menu controls whether to show types in Program
Declaration views. The default is On.
....................................................................................................
Typetext Menu The Typetext menu tells declaration views (Function Declaration, C
File Declaration, Header File Declaration) to include types on the
view. Default is On.
....................................................................................................
Unknown Menu The Unknown menu controls whether entities that are used, but for
which no declaration was found should be drawn. Unknown
methods and entities are those used in the analyzed source without
a definition in the same source.

9-28 Understand 2.0 User Guide and Reference Manual

 Controlling Graphics Layout

....................................................................................................
Unresolved Menu The Unresolved menu controls whether entities that have been
used but no declaration was found should be drawn. This option is
available on hierarchy and structure views. Unresolved functions
and entities are those used in the analyzed source without a
definition in the same source. Unresolved include files are those
included but not found along a declared include path (either a
compiler or project include path).
Unresolved entities are drawn as normal but with a dashed border:

....................................................................................................
Usedby Menu The Usedby menu tells Declaration views whether to show items
that use this item.
....................................................................................................
Uses Menu The Uses menu tells Uses views whether to show only items that
are used directly, or to also show items that are used by nested
subprograms. The default is to show both.
....................................................................................................
Variables Menu The Variables menu controls whether to show globals in
Declaration views. The default is On.
....................................................................................................
Withs Menu The Withs menu controls on Declaration views of compilation units
(packages, tasks, separate procedures, etc...) if Withs are drawn.
The default is On.
....................................................................................................
With Bys Menu Controls if With Bys (who Withs a given compilation unit) are shown
on Declaration views. The default is On.

Understand 2.0 User Guide and Reference Manual 9-29

Chapter 9: Using Graphical Views

Saving Graphical Views

Understand 2.0 offers a number of ways to export your graphical
views and use them in other ways. The toolbar for each graphical
view provides the following icons for printing and exporting graphics.

In addition to printing, you can save graphical views as JPEG, PNG,

SVG, and Visio files. The first three formats are common graphics
formats. The last format requires the Visio software.
....................................................................................................
Saving Views to Files To save a graphical view in one of the following formats, click the
Export to Image File icon on the graphical view toolbar. In the
Export dialog, choose a location, filename, and file type for the view.
• JPEG files are compressed bitmaps. They can be viewed with
most web browsers, document editors, and graphics programs.
This format is “lossy”; some data is lost in the compression.
• PNG files store compressed bitmaps similar to GIF files. They
can be viewed with most web browsers, document editors, and
graphics programs. They use a non-patented compression
method.
• SVG files are Scalable Vector Graphics files. This file type uses
XML to describe a 2-dimensional vector-based image.
You can also copy a graphical view to the clipboard and paste it as a
bitmap into the image program or word processor of your choice. To
do this, click the Copy icon on the graphical view [Link],
paste the image into another program.
....................................................................................................
Saving Views as Visio Microsoft Visio is a vector-based graphics program used for drawing
Files flowcharts and similar graphics. That is, it deals with shapes and
objects rather than pixels.
In order to save a graphical view as a Visio file, you must have Visio
5 or a later version installed on your computer. (Visio 2000 is
equivalent to Visio 6.)

9-30 Understand 2.0 User Guide and Reference Manual

 Saving Graphical Views

To save a Visio file, click the Export to Visio File icon on the
graphical view toolbar.
If Visio is not open, Understand 2.0 opens it and begins creating
objects to match the ones in the graphical view. The process of
creating all the objects may take some time for a large graphical
view. A progress bar is shown in Understand 2.0 while the file is
being created. Avoid exiting Visio or attempting to stop the process
of creating the Visio diagram while it is in progress.
Once the view has been drawn in Visio, use Visio to save the file.

Understand 2.0 User Guide and Reference Manual 9-31

Chapter 9: Using Graphical Views

Printing Graphical Views

Understand 2.0 has these printing modes:
• Source File printing sends a text file to the printer using 66 lines
of source per page. See Printing Source Views on page 6–14.
• Graphical view printing provides options for how to fit the
image to a page. See Graphical View Printing on page 9–32.
....................................................................................................
Graphical View To print the current graphical view, you can click Print icon on
Printing the graphical view toolbar. Or, choose File->Print Entity Graph
from the menus.
When you choose to print a graphical view, you see the Graphic
Print Options dialog.

9-32 Understand 2.0 User Guide and Reference Manual

 Printing Graphical Views

You can choose to print the image at one of the following sizes:
• Full size uses the default scaling of 100%. The dialog shows the
number of pages in width x height format. The page size
selected with Page Setup is used.
• Fit to a single page scales the image to fit on the selected page
size.
• Scale by lets you choose the sizing percentage and shows the
number of pages that will be printed.
Check the Save to PDF file box if you want the image saved to an
Adobe Acrobat file rather than being sent to a printer. This PDF
printing feature does not require that you have third-party PDF
generating software installed on your computer.
Check the Print page number identifiers box if you
want page numbers on each page in the upper-left
corner. The page numbers are in “(column, row)” format.
For example, (1,3) indicates that the page goes in the
leftmost (first) column of the third row when you piece
the pages together. The page number is not printed if the view is
printed on a single page.
Check the Print page border markers box to place corner markers
in each corner of each page.
Click the Printer button to open the standard Print dialog for your
operating system. When you click Print or OK in that dialog, you
return to the Graphic Print Options dialog.
Click the Page Setup button to open a Page Setup dialog, which
allows you to choose the paper size, paper source (if applicable),
page orientation, and margin width. Click OK to return to the
Graphic Print Options dialog.
Click the OK button in the Graphic Print Options dialog to send the
graphical view to the printer (or a PDF file).
Note: The File->Page Setup menu option applies only to printing source
code and other text files. The Page Setup button on the Graphic
Print Options dialog saves its settings separately.

Understand 2.0 User Guide and Reference Manual 9-33

Chapter 9: Using Graphical Views

9-34 Understand 2.0 User Guide and Reference Manual

Chapter 10 Generating Reports
This chapter describes how to create and view reports and the types
of reports available.

This chapter contains the following sections:

Section Page
Configuring Reports 10–2
Generating Reports 10–4
Viewing Reports 10–5
An Overview of Report Categories 10–6
Cross-Reference Reports 10–8
Structure Reports 10–14
Quality Reports 10–18
Metrics Reports 10–23

Understand 2.0 User Guide and Reference Manual 10-1

Chapter 10: Generating Reports

Configuring Reports
Understand 2.0 provides a large number of reports you can
generate about your code. These can be generated in HTML or text
format. You can choose which reports and how to format them.
To begin generating reports, choose Project->Project Reports.

The Configure button opens the Project Configuration dialog with

the Reports->Output category selected. From there, you can also
configure the Reports->Options and Reports->Selected
categories.
See page 3–24 for details on the Reports->Output category. In
general, you can configure the following:
• HTML reports: The “home” file for the reports is [Link], but
you can select an alternate title page. You may generate single
or multiple HTML files for each report type. It is recommended
that you split up the files for large projects. Choose Alphabetic to
generate multiple HTML files per report that are split up
alphabetically by the first letter of the entity name. Choose Every
n Entities to generate multiple HTML files per report that are split
up every “n” number of entities. By default, a single HTML file is
generated for each letter of the alphabet.
• Text reports: You may generate one text file of the specified
name (by choosing File). This one file will contain all the selected
reports. Alternately, you may generate multiple text files (by
choosing Separate Files) and specify a common filename prefix.
The filenames of each text file identify the report.

10-2 Understand 2.0 User Guide and Reference Manual

 Configuring Reports

For details on the Reports->Options category, see page 3–25.

The Reports->Selected category lets you select from the available
reports for the languages used by your project. This list shows all
the reports for all languages:

The specific reports available depend upon the source languages

used in your project.
See An Overview of Report Categories on page 10–6 for
descriptions of the types of reports you can generate.

Understand 2.0 User Guide and Reference Manual 10-3

Chapter 10: Generating Reports

Generating Reports
Once you have specified formatting options and the types of reports
to be generated, click Generate in the Project Reports dialog to
begin generating the selected reports.
On Windows, the ASCII text follows the DOS text file format
(carriage return and line feed at the end of each line). On UNIX, text
files are created according to the UNIX convention (lines end with a
carriage return).
HTML reports are generated as HTML 3.0 format files. The
generated HTML is not complex, the only HTML 3.0 (versus HTML
2.0) feature used is frames. Netscape 2.0 and higher, and Internet
Explorer 3.0 and higher can display the files.
You can view the reports as described in Viewing Reports on
page 10–5.
For large projects, reports can take a long time to generate. You can
click Cancel to halt report generation. Clicking Cancel leaves the
reports in a partially generated state.
Note: You may want to temporarily toggle off anti-virus protection
programs while reports are being generated. This may speed the
process of creating reports. If you do this, be sure to turn on virus
checking after report generation is finished.
Note: HTML, text, and project metrics reports may also be generated with
the “und” command line program. Refer to Chapter 13 for details.

10-4 Understand 2.0 User Guide and Reference Manual

 Viewing Reports

Viewing Reports
To view generated reports, choose Project->Reports. Then click
the View HTML or View Text button.
File names of reports generated vary based on the type and format
of the report generated.
• For text files, a single text file containing all selected reports may
be generated or separate files for each type of report may be
generated. A single text file is named <project_name>.txt. For
separate text files, the file name is the type of report.
• For HTML reports, you can generate either a single HTML files
for each report type, or smaller files divided either alphabetically
by entity name or in groups of N number of entities. An index file
is also generated that contains links to all the other HTML reports
generated. The main window page is named [Link].
For HTML reports, a single index file contains an alphabetic list of all
entities found in all other generated HTML reports. The entities
listed in the index have hyperlinks to the Data Dictionary report for
that entity. The entity index file is named entity_index.html and can
be accessed from the “index” link on the main HTML page.
The following figure shows an example of the entity index.

Understand 2.0 User Guide and Reference Manual 10-5

Chapter 10: Generating Reports

An Overview of Report Categories

Understand 2.0 generates a wide variety of reports. The reports fall
into these categories:
• Cross-Reference reports show information similar to that in the
Info Browser, except that all entities are shown together in
alphabetic order. See Cross-Reference Reports on page 10–8.
• Structure reports show the structure of the analyzed program.
See Structure Reports on page 10–14.
• Quality reports show areas where code might need to be
examined. See Quality Reports on page 10–18.
• Metrics reports show basic metrics such as the number of lines
of code and comments. See Metrics Reports on page 10–23.
The following table shows the type and page number for each
report.
Report Type Report Name and Page
Cross-Reference Data Dictionary Report on page 10–8
Cross-Reference File Contents Report on page 10–10
Cross-Reference Program Unit Cross-Reference Report on page 10–9
Cross-Reference Object Cross-Reference Report on page 10–10
Cross-Reference Type Cross-Reference Report on page 10–11
Cross-Reference Macro Cross-Reference on page 10–12
Cross-Reference Include File Cross-Reference on page 10–12
Cross-Reference Exception Cross-Reference Report on page 10–13
Structure Declaration Tree on page 10–14
Structure Class Extend Tree on page 10–15
Structure Invocation Tree Report on page 10–16
Structure Simple Invocation Tree Report on page 10–16
Structure Import Report on page 10–17
Structure With Tree Report on page 10–16
Structure Simple With Tree Report on page 10–17
Structure Generic Instantiation Report on page 10–17
Structure Renames Report on page 10–17
Quality Program Unit Complexity Report on page 10–18
Quality Uninitialized Items on page 10–20
Quality Unused Variables and Parameters on page 10–21
Quality Unused Objects Report on page 10–21

10-6 Understand 2.0 User Guide and Reference Manual

 An Overview of Report Categories

Report Type Report Name and Page

Quality Unused Types Report on page 10–21
Quality Unused Program Units Report on page 10–22
Quality Withs Not Needed Report on page 10–22
Quality Implicitly Declared Objects Report on page 10–20
Quality FORTRAN Extension Usage Report on page 10–19
Metrics Project Metrics Report on page 10–24
Metrics Program Unit Metrics Report on page 10–25
Metrics File Metrics Report on page 10–26
Metrics File Average Metrics Report on page 10–27
Metrics Class Metrics Report on page 10–24
Metrics Class OO Metrics Report on page 10–25
....................................................................................................
Augment with the The reports included with Understand 2.0 have evolved over many
PERL or C API years to accommodate common customer requests. However, we
recognize that not all needs can be covered.
To help you develop custom reports we include both PERL and C
interfaces to Understand 2.0 databases.
For details on the PERL interface choose Help->PERL API
Documentation and Help->FAQ. Also visit the blog and forum on
our website.
The Project->Project Interactive Reports and Project->Project
Graphical Views commands display a list of user-created plugins,
which can be created using the Perl API. For information about
creating plugins, please contact support@[Link]. The
SciTools forum at [Link] and the
SciTools blog at [Link] also contain messages
concerning plugins.

Understand 2.0 User Guide and Reference Manual 10-7

Chapter 10: Generating Reports

Cross-Reference Reports
Cross-Reference reports show information similar to that in the
References section of the Info Browser, except that all entities are
shown together in alphabetic order. The following table shows the
page that describes each type of cross-reference report.
Report Name
Data Dictionary Report on page 10–8
Program Unit Cross-Reference Report on page 10–9
File Contents Report on page 10–10
Object Cross-Reference Report on page 10–10
Type Cross-Reference Report on page 10–11
Class and Interface Cross-Reference on page 10–11
Macro Cross-Reference on page 10–12
Include File Cross-Reference on page 10–12
Exception Cross-Reference Report on page 10–13
....................................................................................................
Data Dictionary The Data Dictionary Report lists all entities alphabetically. Each
Report listing shows the entity name, what kind of entity it is (for example,

10-8 Understand 2.0 User Guide and Reference Manual

 Cross-Reference Reports

macro, type, variable, function, include, file, or procedure), along

with links to the location where each is declared in the source code.

Optionally break up report alphabetically

Name Quick link to cross-reference of this entity
What kind of entity it is
What file/line it was declared in.
....................................................................................................
Program Unit Cross- The Program Unit Cross-Reference Report lists all program units
Reference Report (such as procedures and functions) analyzed in alphabetic order
along with information about what they return (if anything), what
parameters are used, and where they are used by other program
units.
The HTML version offers hyperlinks to the Data Dictionary report
entry and to the source code where each reference occurs.

Name and
entity type

Link to containing unit

Type of reference What file/line it occurs in in data dictionary

Understand 2.0 User Guide and Reference Manual 10-9

Chapter 10: Generating Reports

You can create an additional Program Unit Index report to list all the
program units in the project and show the file and line where each is
declared. For text reports, this is stored in a *.pcn file.
....................................................................................................
File Contents Report Lists functions declared within a source file and the line numbers
where they are declared. HTML versions of this report permit
hyperlinked jumping to the function in the source as well as viewing
of the entire source file.

....................................................................................................
Object Cross- The Object Cross-Reference Report lists all objects (FORTRAN
Reference Report variables, parameters, macros) in alphabetic order along with
declaration and usage references.

The HTML version of this report includes hyperlinks to the Data

Dictionary Report and the source code where the reference occurs.

10-10 Understand 2.0 User Guide and Reference Manual

 Cross-Reference Reports

....................................................................................................
Type Cross- The Type Cross-Reference Report lists all declared types in
Reference Report alphabetic order, along with their declaration and usage information.
The HTML version of the report offers hyperlinks to the Types data
dictionary report entry, as well as the source code where the
reference occurs.

....................................................................................................
Class and Interface The Class and Interface Cross-Reference Report lists all declared
Cross-Reference classes and interfaces in alphabetic order, along with their
declaration and usage information. The HTML version of the report
includes hyperlinks to the data dictionary report entries, as well as
the source code where the reference occurs.

Understand 2.0 User Guide and Reference Manual 10-11

Chapter 10: Generating Reports

....................................................................................................
Macro Cross- The Macro Cross-Reference Report lists all macros analyzed in the
Reference source code in alphabetic order along with information about where
they are declared and where they are used. The HTML version
offers hyperlinks to the macro’s Data Dictionary report entry and to
the source code where each reference occurs.

....................................................................................................
Include File Cross- The Include File Cross-Reference Report lists all include files
Reference analyzed in the source code in alphabetic order with information
about which files include them. The HTML version offers hyperlinks
to the source code where each reference occurs.

10-12 Understand 2.0 User Guide and Reference Manual

 Cross-Reference Reports

....................................................................................................
Exception Cross- The Exception Cross-Reference Report documents the declaration
Reference Report and usage of all exceptions. Each declaration and any raises or
handles are documented. In the HTML version each raise or handle
may be visited in the source, as well as the declaration point of the
Exception (if visible).

Understand 2.0 User Guide and Reference Manual 10-13

Chapter 10: Generating Reports

Structure Reports
Structure reports are designed to help you understand the
relationships between various entities. The following table shows
the page in this chapter that describes each type of structure report.
Report Name and Page
Declaration Tree on page 10–14
Class Extend Tree on page 10–15
Invocation Tree Report on page 10–16
Simple Invocation Tree Report on page 10–16
With Tree Report on page 10–16
Simple With Tree Report on page 10–17
Generic Instantiation Report on page 10–17
Renames Report on page 10–17
Import Report on page 10–17
....................................................................................................
Declaration Tree The Declaration Tree shows the declaration nesting of each
program unit analyzed. Each nesting level is indicated by an indent
with a vertical bar used to help align your eyes when viewing. Each
nesting level is read as “declares”. In the HTML version of the report
each program unit name is a hyperlink to its entry in the Program
Unit Cross-Reference Report.
Package Body Occupants
| Procedure Put_View
| Procedure Look
| Procedure Get
| Function May_I_Get
| Procedure Drop
| Function May_I_Drop
| Procedure Inventory
| Procedure Go
| | Block
In the above example, Package Body Occupants is the top level
program unit. It has declared within it, Put_View, Look, Get,
May_I_Get, Drop, May_I_Drop, Inventory, and Go. Nested within
Go is an unnamed declare block.

10-14 Understand 2.0 User Guide and Reference Manual

 Structure Reports

The Declaration Tree report shows a textual representation of an

declaration tree for each FORTRAN file.

Subroutines/blocks
declared in file allocate.f

....................................................................................................
Class Extend Tree The Class Extend Tree report shows the nesting of class
declarations in the files analyzed. Each nesting level is indicated by
an indent with a vertical bar to help align your eyes when viewing.
Each nesting level is read as “extends”. In the HTML version of the
report each class name is a hyperlink to its entry in the Data
Dictionary and Interface Cross-Reference Report.

Understand 2.0 User Guide and Reference Manual 10-15

Chapter 10: Generating Reports

....................................................................................................
Invocation Tree The Invocation Tree Report shows a textual representation of the
Report invocation tree for each program unit analyzed. The report shows
who each program unit calls. Levels are indicated by tabs and are
lined up with vertical bars. Each nesting level is read as “calls”.
The HTML version offers hyperlinks to the corresponding Data
Dictionary report entries.

....................................................................................................
Simple Invocation The Simple Invocation Tree Report shows the invocation tree to only
Tree Report one level for each program unit that has been analyzed.
The invocation level is indicated by an indent and a vertical bar and
is read as “calls”.

....................................................................................................
With Tree Report Structured identically to the other hierarchy reports, the With Tree
report shows a textual representation of the With Tree for each
program unit that is not Withed by another.
As with the other textual hierarchy reports, indents show level with a
vertical bar helping align your eye. For this report, each line is read
as “Withs”.
Package Body Occupants
| Package Rename Text_IO
| | Package Text_IO
| | | Package IO_Exceptions
| | | Package System
| | | Package Parameters

10-16 Understand 2.0 User Guide and Reference Manual

 Structure Reports

In the above example, the package body Occupants Withs package

Text_IO, which in turn Withs IO_Exceptions, System,
and Parameters.
....................................................................................................
Simple With Tree The Simple With Tree report is similar to the With Tree report. It
Report shows a textual representation of the With Tree for each program
unit that is not Withed by another. However, it shows only one level
of withs. For example:
Package Body Occupants
| Package Rename Text_IO
....................................................................................................
Generic Instantiation This report lists each package that was created through
Report instantiation.
In the HTML version, the source where it was instantiated and its
Data Dictionary Report entry may be visited from hyperlinks.
My_Int_IO Package Instantiation
FILE: [Link] LINE:12
Instantiated From => INTEGER_IO Generic
Package
....................................................................................................
Renames Report The Renames Report cross-references the use of the Ada
command “renames”, as in:
function Rouge return Color renames Red;
This report lists program units that have been renamed in alphabetic
order. Each rename shows the program unit it renames, and in the
HTML report a hyperlink to the rename instance in the source is
provided.
The Info Browser also identifies packages and program units that
rename others or are renamed.
....................................................................................................
Import Report The Import report lists all source files that import other files and the
files they import. The HTML version offers hyperlinks to the data
dictionary entry for each imported file.

Understand 2.0 User Guide and Reference Manual 10-17

Chapter 10: Generating Reports

Quality Reports
Understand 2.0’s quality reports are designed to provide information
about areas of the analyzed source that might not meet standards or
that hold the potential for trouble. They also identify areas where
extra programming has been done but not needed. This sometimes
identifies areas that aren’t yet complete, or that haven’t been
maintained completely.
The following table shows the page in this chapter that describes
each type of quality report.
Report Name and Page
Program Unit Complexity Report on page 10–18
FORTRAN Extension Usage Report on page 10–19
Implicitly Declared Objects Report on page 10–20
Uninitialized Items on page 10–20
Unused Variables and Parameters on page 10–21
Unused Objects Report on page 10–21
Unused Types Report on page 10–21
Unused Program Units Report on page 10–22
Withs Not Needed Report on page 10–22

The complete list of quality metrics available in Understand 2.0

changes frequently - more frequently than this manual is reprinted.
A complete and accurate list is always available on our web site:
[Link]
....................................................................................................
Program Unit The Program Unit Complexity Report lists every procedure and
Complexity Report function or similar program unit in alphabetic order along with the
McCabe (Cyclomatic) complexity value for the code implementing
that program unit.
The Cyclomatic complexity is the number of independent paths
through a module. The higher this metric the more likely a program
unit is to be difficult to test and maintain without error.
The Modified column shows the cyclomatic complexity except that
each case statement is not counted; the entire switch counts as 1.
The Strict column shows the cyclomatic complexity except && and ||
also count as 1.

10-18 Understand 2.0 User Guide and Reference Manual

 Quality Reports

The Nesting column shows the maximum nesting level of control

constructs in this program unit.

Click column
header for
explanation
of each metric

....................................................................................................
FORTRAN Extension This report lists anywhere your source code has non-standard
Usage Report FORTRAN extensions. The report factors in what variant (F77, F90,
F95) you chose on your project configuration.
For information about what FORTRAN language extensions are
included in this report, see the Change Log on the Scientific
Toolworks website ([Link]

Understand 2.0 User Guide and Reference Manual 10-19

Chapter 10: Generating Reports

The following is a snippet from a sample FORTRAN Extension

Usage report:

....................................................................................................
Implicitly Declared The Implicitly Declared Objects Report lists any variables or
Objects Report parameters that were implicitly declared using FORTRAN’s implicit
declaration mode. Using implicitly declared variables is considered a
risky practice, and this report helps you weed out where the practice
is occurring in your code.
The HTML version offers hyperlinks to the function’s Data Dictionary
report entry.
....................................................................................................
Uninitialized Items The Uninitialized Items report lists items such as variables that are
not initialized in the code. The report is organized by file. Each
uninitialized item within the file is listed by name along with the line
number on which the item is declared. The HTML version offers
hyperlinks to the location where the item is declared.

10-20 Understand 2.0 User Guide and Reference Manual

 Quality Reports

....................................................................................................
Unused Variables The Unused Variables and Parameters report lists items that are
and Parameters declared (and perhaps initialized) but never referenced other than
that. The report is organized by file. Each unused item is listed by
name along with the type of item and the line number on which the
item is declared. The function or similar container is shown after the
list of unused items within it. Types of items may include functions,
parameters, variables, and objects. The HTML version offers
hyperlinks to the location where each unused item is declared.
....................................................................................................
Unused Objects The Unused Objects Report lists objects (for example, variables,
Report parameters, constants) that are declared but never used. The HTML
version has links to the function’s Data Dictionary report entry and to
the source line where the object is declared.

....................................................................................................
Unused Types Report The Unused Types Report lists types that are declared but never
used. The HTML version has links to the function’s Data Dictionary
report entry and the source where the type is declared.

Understand 2.0 User Guide and Reference Manual 10-21

Chapter 10: Generating Reports

....................................................................................................
Unused Program The Unused Program Units Report identifies program units that are
Units Report declared but never used.
Note that this listing in this report doesn’t mean the system doesn’t
need this program unit. For instance, interrupt handlers that are
called by system interrupts are often never “used” within the other
source of the program.

....................................................................................................
Withs Not Needed This report lists, any With statements a program unit has but does
Report not need (by not using items made public by the With statement).
Note that this covers only direct usage in the program unit and
doesn’t account for side effects that may be needed by the program
to operate correctly. For instance, sometimes a package can be
Withed just to start a task or to execute code in its begin/end block.

10-22 Understand 2.0 User Guide and Reference Manual

 Metrics Reports

Metrics Reports
Metrics provide statistical information about your project and
entities, such as the number of lines of code and the complexity of
various entities.
Understand 2.0 provides a number of ways to gather metrics
information. This section describes reports that provide metrics. See
page 11–2 for other ways to gather metrics.
The following table shows the page in this chapter that describes
each type of metrics report.
Report Name and Page
Project Metrics Report on page 10–24
Class Metrics Report on page 10–24
Class OO Metrics Report on page 10–25
Program Unit Metrics Report on page 10–25
File Metrics Report on page 10–26
File Average Metrics Report on page 10–27

The complete list of metrics available in Understand 2.0 changes

frequently—more frequently than this manual is reprinted.
A complete and accurate list is always available on our web site:
[Link]

Understand 2.0 User Guide and Reference Manual 10-23

Chapter 10: Generating Reports

....................................................................................................
Project Metrics The Project Metrics Report provides metric information about the
Report entire project. The metrics reported include: the total number of files,
the total number of program units, and the total number of lines of
source code.

These metrics are also reported on the title page of the HTML
report.
....................................................................................................
Class Metrics Report The Class Metrics Report provides the following metrics for each
class that has been analyzed:
• Total number of lines
• Total number of blank lines
• Total number of lines of code
• Total number of lines that contain comments
• Average number of lines per class
• Average number of comment lines per class
• Average complexity per class
• Maximum complexity within class
• Ratio of comment lines to code lines

10-24 Understand 2.0 User Guide and Reference Manual

 Metrics Reports

....................................................................................................
Class OO Metrics The Class OO Metrics Report provides the following object-oriented
Report metrics for each class that has been analyzed:
• LCOM (Percent Lack of Cohesion): 100% minus the average
cohesion for class data members. A method is cohesive when it
performs a single task.
• DIT (Max Inheritance Tree): Maximum depth of the class in the
inheritance tree.
• IFANIN (Count of Base Classes): Number of immediate base
classes.
• CBO (Count of Coupled Classes): Number of other classes
coupled to this class.
• NOC (Count of Derived Classes): Number of immediate
subclasses this class has.
• RFC (Count of All Methods): Number of methods this class
has, including inherited methods.
• NIM (Count of Instance Methods): Number of instance
methods this class has.
• NIV (Count of Instance Variables): Number of instance
variables this class has.
• WMC (Count of Methods): Number of local methods this class
has.
....................................................................................................
Program Unit Metrics The Program Unit Metrics Report provides information on various
Report metrics for each program unit that has been analyzed.

The following metrics are provided for each program unit:

• Lines: Total number of lines in the function.
• Comment: Number of comment lines in the function.
• Blank: Number of blank lines in the function.
• Code: Number of lines in the function that contain any code.
• Lines-exe: Lines of code in the function that contain no
declaration.

Understand 2.0 User Guide and Reference Manual 10-25

Chapter 10: Generating Reports

• Lines-decl: Lines of code in the function that contain a

declaration or part of a declaration.
• Stmt-exe: Number of executable statements in the function.
• Stmt-decl: Number of declarative statements in the function.
This includes statements that declare classes, structs, unions,
typedefs, and enums.
• Ratio Comment/Code: Ratio of comment lines to code lines.
(comment_lines/code_lines)
Note: code+comment+blank != lines
Some lines may contain both code and comments.
....................................................................................................
File Metrics Report The File Metrics Report provides information similar to that in the
Program Unit Metrics Report. However, it is organized by file rather
than by program unit.
Click on each metric column to get a detailed description of it.
Note: code+comment+blank != lines
Some lines may contain both code and comments.

10-26 Understand 2.0 User Guide and Reference Manual

 Metrics Reports

....................................................................................................
File Average Metrics The File Average Metrics Report provides averages for the functions
Report within a file. All lines outside any function are ignored when
calculating the averages. The following metrics are provided for
each function:
• Cyclomatic: The average number of independent paths through
the functions in this file. The higher this metric the more likely a
program unit is to be difficult to test and maintain without error.
• Modified: Same as Cyclomatic complexity except that each
case statement is not counted; the entire switch statement
counts as 1.
• Strict: Same as Cyclomatic complexity except that && and ||
also count as 1.
• Essential: Measures the amount of unstructured code in a
function.
• Lines: Average number of lines in the functions in this file.
• Code: Average number of lines that contain any code in the
functions in this file.
• Comment: Average number of comment lines in the functions in
this file.
• Blank: Average number of blank lines in the functions in this file.

Understand 2.0 User Guide and Reference Manual 10-27

Chapter 10: Generating Reports

10-28 Understand 2.0 User Guide and Reference Manual

Chapter 11 Generating Metrics
This chapter describes how to create and view metrics and the
types of metrics available.

This chapter contains the following sections:

Section Page
About Metrics 11–2
Project Metrics Summary 11–3
Project Metrics Browser 11–4
Exporting Metrics to HTML 11–5
Exporting Metrics to a CSV File 11–6
Browsing Metric Graphs 11–8

Understand 2.0 User Guide and Reference Manual 11-1

Chapter 11: Generating Metrics

About Metrics
Understand 2.0 provides a number of ways to gather metrics
information:
• Info Browser: The Info Browser tree has a Metrics node. You
can expand this branch to show a few metrics for the current
entity. See page 4–12.
• Project Metrics Summary: You can choose Metrics->Project
Metrics Summary from the menus to see a short list of metrics
for the entire project. You can view these for any snapshot. See
page 11–3.
• Project Metrics Browser: You can choose Metrics->Browse
Project Metrics from the menus to see a browser that lets you
choose any architecture node, file, or entity from any snapshot to
see all the metrics available for that item. See page 11–4.
• Export to HTML: You can click this button in the Project Metrics
Browser to export the full list of metrics for all architecture nodes
and files. See page 11–5.
• Export to CSV: You can choose Metrics->Export Project
Metrics from the menus to create a text file of all the project
metrics in comma-delimited format. See page 11–6. (You can
schedule this export to occur regularly; see page 3–19.)
• Browse Metric Graphs: You can choose Metrics->Browse
Metric Graphs from the menus to open the Metric Browser,
which lets you display graphs of various metrics on an
architecture and snapshot basis. See page 11–8.
• Reports: When you create reports by choosing Project->Project
Reports, some of the reports provide metrics. See page 10–23.
• PERL/C API: A more advanced way to get existing metrics and
calculate new metrics is with the PERL and C API. These
provide full access to the Understand 2.0 database. Choose
Help->PERL API Documentation and Help->FAQ for more
information. Examples and more documentation can be found at
[Link] See page 10–7.
If you have the “Analyst” edition, all metrics capabilities are
available. If you have the “Pro” edition, you can view metric graphs
only for the entire project—not for architecture nodes, files, and
individual entities—and cannot export metrics to HTML. If you have
the “Engineer” edition, you also cannot use the Project Metrics
Browser and cannot export metrics to a CSV file.

11-2 Understand 2.0 User Guide and Reference Manual

 Project Metrics Summary

Understand 2.0 provides a large number of metrics you can

generate about your code. The complete list of metrics available in
Understand 2.0 changes frequently—more frequently than this
manual is reprinted.
A complete and accurate list is always available on our web site at
[Link] The “What do the
metric names mean?” buttons in metrics dialogs link to this page.

Project Metrics Summary

Choose Metrics->Project Metrics Summary from the menus to
see a short list of metrics for the entire project.

Use the Snapshots drop-down to switch between snapshots. If you

click Copy All, you can paste the current metrics into another
application.

Understand 2.0 User Guide and Reference Manual 11-3

Chapter 11: Generating Metrics

Project Metrics Browser

To open the Project Browser, choose Metrics->Browse Project
Metrics from the menus.
In this window, you can browse the architectures in your project and
select any architecture node, file, or entity. The list on the right
shows code size and complexity metrics for the selected item.

The Snapshots drop-down near the top lets you select a snapshot
for which to view metrics. The default is the current project files.
Double-click a file or entity to open the Source Editor for that item.
Right-click to see the standard informational menu choices.
You can select rows on the right and click Copy Selected or press
Ctrl+C to copy those lines to the clipboard. Click Copy All to copy
the full list of metrics for the selected directory or file.
Click Export to HTML to generate reports as described on
page 11–5. Click Generate Detailed Metrics to open the Export
Metrics dialog and generate a text file in comma-delimited format as
described on page 11–6.
Selecting entities in the architecture tree and the Export to HTML
button are available on if you have the “Analyst” edition. If you have
the “Pro” edition, you can select architecture nodes and files only.

11-4 Understand 2.0 User Guide and Reference Manual

 Exporting Metrics to HTML

Exporting Metrics to HTML

You can click the Export to HTML button in the Project Metrics
Browser (page 11–4) to export the full list of metrics for all
architecture nodes and files. When you click this button, you see a
Browse for Folder dialog appropriate to your operating system.
Choose or create the folder where you want the metrics files to be
created. The files are actually stored in a folder called
“pixie_proj_Metrics“ below the folder you select.
If the directory already exists, you are asked if the files should be
overwritten. If you answer “No”, a number is appended to the old
directory name to it to save it as a backup.
If the report is generated successfully, you are asked if you want to
view the report. Click Yes to open the top-level page, [Link].

The HTML-based report lets you select any architecture node or file
in the left pane. The right pane shows metrics available for that item.

Understand 2.0 User Guide and Reference Manual 11-5

Chapter 11: Generating Metrics

Exporting Metrics to a CSV File

You can save metric information to a comma-delimited text file by
choosing Metrics->Export Project Metrics from the menus or
clicking the Generate Detailed Metrics button in the Project Metrics
Browser. You can use the generated file in Excel and other
spreadsheet programs. The Export Metrics dialog looks like this:

The defaults in this dialog come from the Project Configuration

dialog in the Metrics->Options category (page 3–22) and the
Metrics->Selected category (page 3–23).
You can override the defaults using the following fields:
• Available Metrics: Check the boxes next to metrics you want to
include in the output. Check the “SELECT ALL” box to select all
metrics. Uncheck the “SELECT ALL” box to unselect all metrics.
• Metrics to Export: Click the single arrow to move the selected
metric up or down one in the list. Click the double arrow to move
the selected metric to the top or bottom of the list.

11-6 Understand 2.0 User Guide and Reference Manual

 Exporting Metrics to a CSV File

• Save output to: Specify the location and name of the file you
want to use for metrics output. Understand 2.0 sends its metrics
output to a .csv (comma-separated values) file.
• Show File Entity Name as: Specify whether files should be
displayed with Short names (just the filename), Full names
(including the absolute path), or Relative names (relative
directory path).
• Show Declared in File: Check this box if you want the file in
which each entity is declared to be included in the output. You
can specify whether you want these files displayed with Short
names, Full names, or Relative names.
• Write Column Titles: Check this box if you want column
headings in the CSV file.
• Show Function Parameter Types: Check this box if you want
the type of each function parameter listed.
After setting options, click Export to export the .CSV file. If you
check the View File After Export box before exporting the file, the
CSV file is opened with the default application for working with CSV
files. This is likely to be a spreadsheet application.
If the output file already exists, you are asked if the files should be
overwritten. If you answer “No”, you can change the output filename
and click Export again.
You can schedule this metrics to be automatically exported to a
CSV file on a regular basis. See page 3–19 for details.
A complete and accurate list of the available metrics is available at:
[Link]

Understand 2.0 User Guide and Reference Manual 11-7

Chapter 11: Generating Metrics

Browsing Metric Graphs

Commands in the Metrics menu provide fast access to metrics
graphs for the current version of the entire project. These
commands are:
• Metrics->Code Volume*
• Metrics->File Volume*
• Metrics->Average Complexity
• Metrics->Sum Complexity
* If you have the “Engineer” edition, you can display the Code
Volume and File Volume graphs for the entire project only. If you
have the “Pro” edition, you can display the four graphs listed above
for the entire project only. If you have the “Analyst” edition, all
metrics graphing features described in this section are available.
You can choose Metrics->Browse Metric Graphs from the menus
to open the Metric Browser, which lets you display graphs of various
metrics on an architecture and snapshot basis.

In this browser, select the following:

11-8 Understand 2.0 User Guide and Reference Manual

 Browsing Metric Graphs

• Project Metrics: Select the type of metrics you want to graph

from the drop-down list. For descriptions and a list of which
metrics apply to various languages and entity types, see the list
at [Link]
- Code Volume: Provides a stacked vertical bar chart showing
the count of lines that are blank, contain declarations and
executable code, and contain comments.
- File Volume: Provides a vertical bar chart showing the
number of files in the selected architecture node that are code
files vs. header files (or the number of files for languages that
do not have header files).
- Average Complexity: Provides a vertical bar chart of the
average and maximum cyclomatic complexity for all nested
functions or methods in the architecture node, along with the
maximum nesting level of control constructs in the node’s files.
- Sum Complexity: Provides a vertical bar chart showing the
number of possible paths through the code and the sum of the
cyclomatic complexity and the essential complexity of all
nested functions or methods.
• Architecture: Check boxes next to one or more architecture
nodes, files, and/or entities. The graph will provide a set of
vertical bars for each of the items you select.
• Snapshots: Check boxes next to one or more project
snapshots. The graph will provide a separate tab for each
snapshot you select.
Click the icon to display a graph for your selections in a tab. If
you have already selected a graph for this type of project metrics,
that tab will be reused. Click the icon to open a new tab to
display a graph for your selections.

Understand 2.0 User Guide and Reference Manual 11-9

Chapter 11: Generating Metrics

A typical metrics graph looks similar to the following:

In a graph, you can choose the Graph View or the Table View. Both
views have a toolbar that lets you save the graph or data.
In the Graph View, you can use the toolbar to:

• Save the image as a PNG, JPEG, or BMP image.

• Copy the image to the clipboard.
• Print the image using the standard Print dialog.

11-10 Understand 2.0 User Guide and Reference Manual

 Browsing Metric Graphs

In the Table view, the numeric values for each pie slice or vertical
bar is shown in a table. You can use the toolbar to copy the data to
the clipboard in comma-separated (CSV), tab-separated, or table
format (spaces used so columns align with headings if a font such
as Courier is used).

If you selected multiple snapshots, tabs just below the toolbar let
you quickly switch from one snapshot to another.
If you are viewing data for several architecture nodes, you can
change the number in the lower-right corner to the number of
vertical bars you want to view on each page and click the checkmark
icon. Then use the arrows in the corners to move from page to page.
The text shows which vertical bars are currently shown out of the
total number. For example, the figure below indicates that bars 3
and 4 out of a total of 5 are currently shown.

Understand 2.0 User Guide and Reference Manual 11-11

Chapter 11: Generating Metrics

11-12 Understand 2.0 User Guide and Reference Manual

Chapter 12 Running External
Commands
This chapter will show you how to configure and use source code
editors and other external tools from within Understand 2.0.

This chapter contains the following sections:

Section Page
Using an External Editor 12–2
Configuring Tools 12–3
Adding Tools to the Right-Click Menus 12–10
Adding Tools to the Tools Menu 12–12
Adding Tools to the Toolbar 12–13
Importing and Exporting Tool Commands 12–14
Running External Commands 12–15

Understand 2.0 User Guide and Reference Manual 12-1

Chapter 12: Running External Commands

Using an External Editor

You can use an editor other than the one provided with Understand
2.0 for viewing and editing your source code. The editor you select
is used whenever you open source code. This provides convenient
source navigation while using a familiar editor. For example, you
can use Microsoft Visual C++ or Emacs as your editor.
You should choose an editor that accepts command line parameters
that specify the file to open, and a line and column number to go to.
To change the editor, follow these steps:
1 Choose Tools->External Editor Settings.
2 In the Select an External Editor dialog, check the Use External
Editor box if you do not want to use Understand 2.0 for editing.

3 In the Editor field, click the folder icon and select the executable
file for the editor you want to use.
4 In the Parameters field, type the command line parameters you
want to use when opening the editor. Use the $File, $Line, and
$Col variables to allow Understand 2.0 to open source files to the
correct location.
For example, for the GVIM editor on UNIX, the Editor is “gvim”, and
the Parameters should be as follows (for GVIM 6.0 or later):
--servername UND --remote +$line $file
For the TextPad editor on Windows, the Editor is most likely
c:\Program Files\textpad4\[Link], and the Parameters should
be as follows:
$file($line,$col)

12-2 Understand 2.0 User Guide and Reference Manual

 Configuring Tools

The Understand 2.0 right-click menus (also called context menus)

can be made usable in external editors. Steps for doing this are
provided in the SciTools blog. For EMACS, vi, and Visual Studio, see
[Link]
[Link]. For SlickEdit, see [Link]
[Link].

Configuring Tools
Select Tools->Configure User Tools from the menus to open the
Tool Configurations dialog, where you can configure external tools
such as source code editors for use within Understand 2.0. External
tools configured for use will be available for context-sensitive
launching. The Tool Configurations dialog provides a number of
categories that determine how they are launched.
First, use the User Tools category of the Tool Configurations dialog
to define a command and parameters as follows:

Understand 2.0 User Guide and Reference Manual 12-3

Chapter 12: Running External Commands

1 Click New.
2 In the Menu Text field, type the name you want to appear in
Understand 2.0 menus for this tool. You can use variables in the
Menu Text. For example, you can use $CurEntity to put the name
of the currently selected entity in the tool name. See Variables on
page 12–5 for a full list of variables.
3 If the tool you use is on your executable search path, simply type
its name in the Command field. If not, use the Browse button to
specify the full path to its executable.
4 In the Parameters field, specify parameters that need to be
passed on the tool’s command line. See Variables on page 12–5
for a full list of variables. Variables beginning with $Cur are
current position variables that apply only from a Source Editor
window. Variables beginning with $Decl are declaration variables
that apply only when an entity with a declaration is selected.
Variables beginning with $Prompt display a dialog to ask the
user for some information.
5 In the Initial Directory field, specify the directory in which the
tool should start running. You can use variables such as
$CurProjectDir in this field.
6 In the Icon file field, type or browse for a small graphic file to act
as the icon for this command. You can choose a BMP, GIF,
PBM, PGM, PNG, PPM, XBM, or XPM file.
7 Check the Capture output of command line tool box if you
want to send the output from the tool to a Command Window in
Understand 2.0.
This command window is reused by default if you run another
tool or re-run the same tool. You can force results to go to a new
window either by unchecking the Reuse box on the command
results window(s), or by holding down the CTRL key when
choosing the user tool you have added.
8 In the “Add to...” area, choose ways you want to access this
command in Understand 2.0. The Pop Up Menu checkbox adds
the tool to the right-click pop-up menu. The Main Menu
checkbox adds the tool to the Tools->User Tools submenu. The
Toolbar checkbox adds the tool’s icon to the toolbar.
9 Check the Understand perl script box if this is a Perl script that
uses the Understand Perl API.
To edit settings for an existing tool, select it in the list and make
changes as needed. Click OK to save your changes. If you want to
remove a tool, select it and click Delete.

12-4 Understand 2.0 User Guide and Reference Manual

 Configuring Tools

For information about using the Import button, see Importing and
Exporting Tool Commands on page 12–14.
....................................................................................................
Variables Variables beginning with $Cur are current position variables that
apply only from a Source Editor window. Variables beginning with
$Decl are declaration variables that apply only when an entity with a
declaration is selected. Variables beginning with $Prompt display a
dialog to ask the user for some information.
You can use the following variables in the Command or the
Parameter field.

Variable Description
$CurCol Column position of cursor position in current file.
$CurEntity Full name of selected entity.
$CurEntityShortName Short name of selected entity.
$CurFile Current file's full path.
$CurFileDir Current file's directory.
$CurFileExt Current file's extension.
$CurFileFlatStr Current file's full path with all directory separation characters (such
as / and \) replaced with an underscore (_).
$CurFileName Current file's name not including extension or full path.
$CurFileShortName Current file's name without full path.
$CurLine Line number of cursor position in current file.
$CurProject Current fullname location of opened project.
$CurProjectDir Directory in which the opened project is located.
$CurProjectName Current short filename of opened project (not including extension).
$CurReportHtml Current fullname location of opened project's HTML report.
$CurReportText Current fullname location of opened project's CSV report.
$CurScopeEntity Scope of current entity.
$CurSelection Currently selected text in the current window (file windows only).
$CurWord The word/text at the current cursor position in the current file
window.
$DeclCol Column in which the selected entity was declared, defaults to 1.
$DeclFile Full path name of the file in which the selected entity was declared.
$DeclLine Line in which the selected entity was declared, defaults to 1.

Understand 2.0 User Guide and Reference Manual 12-5

Chapter 12: Running External Commands

Variable Description
$PromptForCheckBox Prompts user for a true/false value required by the command. A 0
(unchecked) or 1 (checked) is passed to the command in place of
this variable. This variable should be followed by a string to be
displayed as text next to the checkbox. For example,
$PromptForCheckBox "Show Debug Text" displays the
following prompt

$PromptForCheckBoxGH Prompts user with a series of checkboxes displayed in a horizontal

group. For example, $PromptForCheckBoxGH "Show=Debug
Text;Tool Tips;Line Numbers" displays the following
prompt. The label (“Show” in this example) is optional. A
semicolon must be used to separate items. The text strings for all
checked items (separated by spaces) are passed to the command.

$PromptForCheckBoxGV Prompts user with a series of checkboxes displayed in a vertical

group. For example, $PromptForCheckBoxGV "Show=Debug
Text;Tool Tips;Line Numbers" displays the following
prompt. The text strings for all checked items (separated by
spaces) are passed to the command.

$PromptForDir Prompts user to select a directory and passes the full path as a
string. For example, $PromptForDir "Directory
Path=$CurProjectDir" displays the following prompt with the
current project directory as the default. The “...” button opens the
standard directory selection dialog for your operating system:

12-6 Understand 2.0 User Guide and Reference Manual

 Configuring Tools

Variable Description
$PromptForFile Prompts user to select a file and passes the full path as a string.
For example, $PromptForFile "Filename=$CurFile"
displays the following prompt with the current source file as the
default. The “...” button opens the standard file selection dialog for
your operating system:

$PromptForRadioBoxGH Prompts user for a selection from a set of options displayed

horizontally. For example, $PromptForRadioBoxGH
"Format=PNG;BMP;GIF;JPEG" displays the following prompt.
The text string for the selected item is passed to the command.

$PromptForRadioBoxGV Prompts user for a selection from a set of options displayed

vertically. For example, $PromptForRadioBoxGV
"Format=PNG;BMP;GIF;JPEG" displays the following prompt.
The text string for the selected item is passed to the command.

$PromptForSelect Prompts user to select from a drop-down box. For example,

$PromptForSelect "Build
Version=Debug;Release;Optimized" displays the following
prompt. The text string for the selected item is passed to the
command.

Understand 2.0 User Guide and Reference Manual 12-7

Chapter 12: Running External Commands

Variable Description
$PromptForSelectEdit Prompts user to select from a drop-down box or edit the text in the
box. For example, $PromptForSelectEdit "Build
Version=Debug;Release;Optimized" displays the same
prompt as the example for $PromptForSelect, except that you can
edit the string in the box.
$PromptForText Prompts user for a string required by the command. For example,
$PromptForText "Replace=foo" displays the following
prompt and provides a default value. The text provided is passed
as a string.

In general, the multiple-selection $Prompt variables accept strings

of the format "label=item1;item2". Any number of items may
be separated by semicolons. The item strings for all selected items
(separated by spaces) are passed to the command.
The label is optional except in the cases of $PromptForCheckBox,
$PromptForDir, $PromptForFile, and $PromptForText. The default
value is optional in the cases of $PromptForDir, $PromptForFile,
and $PromptForText.
Prompts are processed after the other types of variables, so you can
use other variables in the labels and values. For examples, see
$PromptForDir and $PromptForFile in the previous table.
In addition, operating system environment variables can be used in
prompt syntax. For example, $PromptForSelect "Dir=$PATH"
presents a drop-down list of all the directory paths in your $PATH
definition.
You can optionally provide the item list in a separate file. In that
case, the syntax for most $Prompt variables is
label=@fullpath_of_listfile.txt.

12-8 Understand 2.0 User Guide and Reference Manual

 Configuring Tools

You can combine variables to pass all the parameters needed by a

command. All prompts are combined into one dialog. For example if
the command is “ls”, you can use the following parameters to create
a dialog that lets you select command-line options for the ls
command:
$PromptForRadioBoxGH "Show option=-A;-a"
$PromptForSelect "Sort=-e;-t" $PromptForCheckBoxGV
"Additional flags=-d;-D;-l;-L;-s;-l;-u;-x;-c"
$PromptForDir "Dir:=$CurProjectDir"

Understand 2.0 User Guide and Reference Manual 12-9

Chapter 12: Running External Commands

Adding Tools to the Right-Click Menus

Once a command is defined in the Tools tab, the Pop Up Menu
category in the Tool Configurations dialog lists user tools that are
currently in the right-click pop-up menu on the left and commands
you can add to that menu on the right.

To add a tool to the pop-up menus, select it on the right and click
Add. To remove a tool from the pop-up menus, select it on the left
and click Remove.
User tools appear on the right-click menu in the order they are listed
in the left column. Use the Move Up and Move Down buttons to
sort the tools as desired.
The following figure shows a right-click menu for an entity showing
the available external tools.

12-10 Understand 2.0 User Guide and Reference Manual

 Adding Tools to the Right-Click Menus

Tools are active or inactive on the right-click menu based on the

context of the parameters provided to the tool. For example, a
source editor that specifies $DeclFile as a parameter is selectable
from the right-click menu for any entity where the declaration is
known, but will not be active for an undeclared entity or when no
entity is selected.

Understand 2.0 User Guide and Reference Manual 12-11

Chapter 12: Running External Commands

Adding Tools to the Tools Menu

Once a command is defined in the Tools tab, the Main Menu
category in the Tool Configurations dialog lists user tools that are
currently in the Tools->User Tools menu on the left and commands
you can add to that menu on the right.

To add a tool to the menus, select it on the right and click Add. To
remove it from the menus, select it on the left and click Remove.
User tools appear on the Tools menu in the order they are listed in
the left column. Use the Move Up and Move Down buttons to sort
the tools as desired.

12-12 Understand 2.0 User Guide and Reference Manual

 Adding Tools to the Toolbar

Adding Tools to the Toolbar

Once a command is defined in the Tools tab, the Toolbar category
in the Tool Configurations dialog shows user tools currently in the
toolbar in the left box and commands you can add to the toolbar in
the right box.

To add a tool to the toolbar, select it on the right and click Add. To
remove it from the toolbar, select it on the left and click Remove.
To add a vertical separator to the toolbar, select the item in the
Toolbar order box that should have a vertical line to the right of it.
Click Insert Separator to add “-----------” to the list.
Icons for the selected tools appear on the toolbar in the order they
are listed in the left column. Use the Move Up and Move Down
buttons to sort the icons as desired.
To change the icon for a particular tool, use the Icon file field in the
User Tools category.
For example, in the following figure, the first icon is provided by
Understand 2.0 to open the Tool Configurations dialog. The second
icon is the default icon for a user tool if none is specified.

In this toolbar, two icons have been added for user tools. A
separator has been added between them.

Understand 2.0 User Guide and Reference Manual 12-13

Chapter 12: Running External Commands

Note: You can control which icons are visible in the main toolbar by right-
clicking on the background of the toolbar and checking or
unchecking items for the various toolbar sections.

Importing and Exporting Tool Commands

You can import and export tool commands from files. This makes it
easy to share tool commands with co-workers.
1 To export commands, choose Tools->Configure User Tools
from the menus and switch to the Export Tools category. You will
see the following dialog.

2 Check the boxes next to commands you want to share.

3 Click Export to file.
4 Choose a location and filename for an initialization file (*.ini) that
contains the selected user tool information.
5 Click Save.
To import commands, choose the User Tools category in the Tool
Configurations dialog and click the Import button. Browse for an
initialization file created by another Understand 2.0 user and click
Open. In the Import User Tools dialog, check the boxes next to the
tool commands you want to be available in your copy of Understand
2.0.

12-14 Understand 2.0 User Guide and Reference Manual

 Running External Commands

Running External Commands

The Tools->Run a Command menu item permits any external
command to be run directly from Understand 2.0. Common
commands to invoke are compilers, configuration management
tools, and Perl programs written using Understand’s API.
The Run a Command dialog looks like this:

To run a command, follow these steps:

1 Type a Command or click ... and browse for a file to run. A
number of Perl programs are provided in the Understand 2.0
installation.
2 Type any command-line Parameters required by the command.
Click the right arrow if you want to select one of the special
variables. These are listed on page 12–5.
3 Click ... and browse for the directory that should act as the
Working Directory.
4 If you want the output sent to a window in Understand 2.0, leave
the Capture Output box checked.

Understand 2.0 User Guide and Reference Manual 12-15

Chapter 12: Running External Commands

5 If you are running a Perl script, check the STI Perl script box if
this is a script provided by Scientific Toolworks.
6 Click Run. The output is shown in a Command Window in
Understand 2.0 if you checked the Capture Output box.
Otherwise, the command runs in the background and output is
shown in the Running Commands box. You can select a
command from this list and click Stop to halt the command.

The font used in the Command Window is determined by settings in

the Command Window category of the Understand Options dialog,
which you can open by choosing Tools->Options from the menus.
See page 3–59.
On UNIX systems, output to both stdout and stderr are captured.

12-16 Understand 2.0 User Guide and Reference Manual

Chapter 13 Command Line Processing
This chapter shows how to create an Understand 2.0 database by
analyzing your source code, and how to generate reports from the
command line. Command-line processing can be used in a batch file
for automatic re-building and report generation of projects.
This chapter describes the “und” command-line programs, which
allows you to analyzes sources and create Understand 2.0
databases from the command line. In addition, it allows you to
generate reports.
(The “und” program replaces the previous und* and rep* language-
specific programs. Existing batch files and shell scripts that ran the
old programs will need some modification.)
Most examples in this chapter refer to C/C++ files. However, you
can use “und” with any supported language.

This chapter contains the following sections:

Section Page
Using the und Command Line 13–2
Using the understand Command Line 13–11

Understand 2.0 User Guide and Reference Manual 13-1

Chapter 13: Command Line Processing

Using the und Command Line

A command line tool for creating and building Understand 2.0
databases is und. This command line program parses your source
code to populate the database with information that can be browsed
or reported on.
If you will use the “und” tool frequently, you should put it in your
operating system’s PATH definition.
The “und” command line takes the following form, where filename is
the project database file and is a required argument.
und -db filename [options]
Create a new database using the -create option and then load the
files into the database with the -addDir and -addFiles options.
To parse all files, specify -analyze.
The effects of all commands are permanent. There is no option to
make temporary changes as there was in previous versions.
All options that set the configuration are performed before any report
or analyze options, no matter what the sequence of the options on
the command line.
Refer to the sections that follow for details on all the available
command line options and how to create and analyze a project.
....................................................................................................
Getting Help on Since we do frequent builds of Understand 2.0, it is likely that this
Command Line manual may not describe all the options of the “und” command line.
Options The und tool lists its command line options when passed the -help
option:
und -help
Individual options provide a brief explanation when passed with the
-help option. The following example explains the -create option.
und -help create
Some options are only listed in the command-line help if you get
help on their master option. For example:
und -help addDir
You can use the -list option to get a list of language-specific settings
for an option. For example, the following command lists the
available settings for a C++ project for the -compiler_name option.
und -db myproject -C++ -list compiler_name

13-2 Understand 2.0 User Guide and Reference Manual

 Using the und Command Line

The following command lists the available strings you can use after
the -list option.
und -db myproject -list
....................................................................................................
Creating a New There are several ways to create a new project file using “und”. Of
Project course you can use the graphical interface of Understand 2.0 to first
create your project, but here we will examine a few ways to do it
from the command line.
To create a new, empty, project called [Link]:
und -create -db myproject
This example creates a database called [Link].
....................................................................................................
Creating a Project You can create and add files to the database all in one command.
and Adding Sources For example:
in One Step und -db [Link] -create -addDir \usr\myfiles
....................................................................................................
Adding Files to a If you have a small number of source files then it may be easiest to
Project just supply their names to the analyzer using the wildcarding abilities
of your operating system shell. In this example we will process all
source files in the folder:
und -db [Link] -addDir \usr\myproject
In some cases, there may be too many file locations to use the -add
technique. A common command line limitation is 255 characters. A
directory with hundreds or thousands of files may easily exceed this
limit. In this case, or when you want more fine-grained/repeatable
control over what files are processed, you should create a “listfile”.
This file must have a format of one filename per line:
c:\myfiles\myproject\myproject.c
c:\myfiles\myproject\myproject.h
c:\myfiles\myproject\support.c
c:\myfiles\myproject\io.c
c:\myfiles\myproject\io.h
h:\shared\allprojects\file2.c
h:\options\file3.c
h:\options\file4.c
h:\options\file5.c
. . .
is processed via the -addFiles command line option:
und -db myproject -C++ -addFiles @[Link]
Note that there is no limit on the number of files listed in the list file.

Understand 2.0 User Guide and Reference Manual 13-3

Chapter 13: Command Line Processing

....................................................................................................
Creating a List of On UNIX here are a couple ways to create such a file:
Files
• Use the ‘ls’ command, as in:
ls *.c *.h > my_project.lst
• Use the ‘find’ command to recurse subdirectories, as in:
find . -name “*.c *.h” -print > my_project.lst
In a Windows command shell:
• Use the dir command with the /b option:
dir /b *.c *.h > my_project.lst
• Use the /s option to recurse subdirectories, as in:
dir /b /s *c *.h > my_project.lst
....................................................................................................
Analyzing a Project The “und” command line program allows you to analyze (or re-
analyze) a previously created project database.
When analyzing a project, you have several options to choose from.
You may re-analyze all files with the -analyzeAll option, only those
files that have changed with the -analyze option, or a list of files with
the -analyzeFiles option.
If you are doing your first analysis after creating a new project, it
doesn’t matter which option you choose as it will parse all files
regardless. However, if you are performing this function on a regular
basis, you may prefer to do an incremental analysis where only the
modified files and any other files dependent on those files are re-
analyzed.
For example, you can parse all files in the project with the following
command:
und -db [Link] -analyzeAll
Or, to perform an incremental analysis, re-parsing only those files
that have changed or other dependent files, use the command:
und -db [Link] -analyze
This command checks each file previously parsed into the
repository to see if it has changed. If it has changed then it will re-
parse it, and any files that depend on it (and so on) until the
database is fully refreshed.
Use this feature to keep your database up to date while keeping
your parsing to a minimum.

13-4 Understand 2.0 User Guide and Reference Manual

 Using the und Command Line

....................................................................................................
Command Line The only required option for all commands using “und” is the -db
Options option to specify the project database file.
Command-lines for multi-language projects must also use an option
to specify which language you are configuring if you use a project
configuration options. For example: -C++, -Java, or -Pascal.
Where a command accepts a @[Link] for an option, the file must
contain one item per line. Full or relative paths may be used.
Relative paths are relative to the -cwd directory. A # sign in the first
column of a line in the file indicates a comment. If an item has a
definition, for example a macro definition, the macro name and its
value must be separated by an = sign. For example, DEBUG=true.
The following table lists the command line options (also called
command-line switches) for “und”:

Option Description
-db filename Specify the name of the database to create or open. An
extension of .udb is provided if no extension is given.
You can use a filename in the current directory or a full
path to the file. This option is required for most actions.
-Ada Sets the language that this configuration applies to.
-Assembly Required for configuration actions on multi-language
-C++ projects when you set items that apply to multiple
-C# languages, such as -include.
-Fortran
-Java
-Jovial
-Pascal
-Plm
-addDir directory Add the specified directory as a source file directory to
the project. When adding directories, you can also use
the following -addDir* options.
-addDirExcludes wildcard1 Add the specified paths or wildcard patterns to the list
wildcard2... of files to be excluded from the project.
-addDirFilters wildcard1 wildcard2... Use the specified filetype filters to match source files in
the directories specified by -addDir.
-addDirLangTypes lang1 lang2... Add only files that match the filetypes for the specified
languages.

Understand 2.0 User Guide and Reference Manual 13-5

Chapter 13: Command Line Processing

Option Description
-addDirSubdirs [On/Off] Specify On if you want subdirectories of the directory
specified with -addDir to also be added.
-addDirWatch [On/Off] Specify On if you want the added directory to be a
watched directory.
-addFiles file1 file2 ... Add the listed files to the project. Filenames can be
or -addFiles @[Link] relative to -cwd or can use a full path.
-analyze Analyze (parse) any changed files in the project.
-analyzeAll Analyze all files in the project.
-analyzeFiles file1 file2... Analyze the specified list of files.
or -analyzeFiles @[Link]
-arch <name> Specify the name of an existing architecture for use
with other options.
-archDelete Delete the architecture specified with the -arch option.
-archRename newname Rename the architecture specified with the -arch
option.
-archExport [Link] Export XML for the architecture specified with the -arch
option.
-archImport [Link] Import XML for an architecture from the specified file.
-assembler name Set the configured name of the assembly language
assembler.
-changeReportDir path Sets the directory to which the change report should be
written.
-classpath file1 file2... Append to the current Java classpath list. Set to “none”
or -classpath @[Link] to clear the list. The filename may be a class path or a
jar file.
-compiler_includepath [path | “none”] Set the include path for the compiler for C++.
-compiler_name name Set the configured compiler for the specified language.
-compiler_version version Set the configured version of the compiler.
-create Create a new project with the given -db filename. If the
.udb file exists, it will be replaced with new empty
project. Use -languages to set the source code
language(s) for the new project.

13-6 Understand 2.0 User Guide and Reference Manual

 Using the und Command Line

Option Description
-cwd directory Set the current working directory for other relative
filenames, such as those provided with -db and
-report_htmldir.
-define macro1=def1 macro2=def2... Defines macros that may be used with #ifdef and
or -define @[Link] similar preprocessor directives.
-fileType ext1=lang ext2=lang... Add a file extension and specify the language it should
be treated as.
-fileTypeDel ext1 ext2... Delete the specified file extensions associations.
-help option Provide information about an option.
-include includedir1 includedir2... Add the specified directories to the list of include
or @[Link] directories.
-include_addfound [On/Off] Set to On if you want include files found when
analyzing a project to be automatically added to the
source file list.
-include_addfoundsys [On/Off] Set to On if you want system include files found when
analyzing a project to be automatically added to the
source file list.
-include_case [On/Off] Set to On if you want to use case-insensitive searching
for include files.
-include_search [On/Off] Set to On if you want to search for include files among
project files.
-include_treatsys [On/Off] Set to On if you want to treat system include files as
user include files.
-languages lang1 lang2... Specify the source code languages used by the
project.
-list option List the available settings for the specified command-
line option.
-list_tersemode [On/Off] Turns a shorter list from the -list option on or off.
-listarch List all the architecture names in the project.
-listfiles List all the files in the project database.
-listfilestree List all the files in the project database in tree format
showing watched states.

Understand 2.0 User Guide and Reference Manual 13-7

Chapter 13: Command Line Processing

Option Description
-metrics [outputfile] Generate list of currently selected metrics. If an
outputfile is optionally specified, send the output to that
file.
-metrics_sel metric1 metric2... Add the specified metrics to the list to generate. To
or -metrics [all/none] clear the list, use none. Use -list metrics_sel to get a
list of metric names.
-metrics_DeclFilename Specify whether “declared in” filenames should be
[none/short/relative/full] shown as short, relative, full, or not at all (none).
-metrics_Filename [short/relative/full] Specify whether filenames should be shown as short,
relative, full, or not at all (none).
-metrics_Parameters [On/Off] Set to On if you want function parameter types shown
in metrics output.
-metrics_Titles [On/Off] Set to On if you want column headings in metrics
output.
-odefine macro1=def1 [...] Append to the current override macro list for the
or -odefine @[Link] specified file or directory. Must also use the -override
option. Set to “none” to clear the list.
-oinclude includedir [...] Append to the current override include list for the
or -oinclude @[Link] specified file or directory. Must also use the -override
option. Set to “none” to clear the list.
-option_Cache [On/Off] Set the C++ option to toggle the include cache.
-option_RefMacroExpand [On/Off] Set the C++ option to create references to macros
during macro expansion.
-option_Save_Comments [On/Off] Set the option to save comments associated with
entities.
-override file/directory Modify the override settings for the specified file or
directory. This option is required with the -odefine and
-oinclude options.
-process [Link] Pass a file containing command-line options to und.
The most recent -db setting is use for commands in the
file.
-quiet [On/Off] Set to On if you want only errors that would cause a
failure to be reported to the display.

13-8 Understand 2.0 User Guide and Reference Manual

 Using the und Command Line

Option Description
-removeDir directory Remove the specified directory and its subdirectories
from the project. If a directory is watched, it is set to
exclude.
-removeFiles file1 file2 ... Remove the listed files to the project. Filenames can
or -removeFiles @[Link] be relative to -cwd or can use a full path. If the files are
watched files, they are set to excluded files.
-report html text Generate currently selected reports. If html or text is
optionally specified, generate only that type of output.
-report_sel report1 report2... Add the specified reports to the list to generate. To
or -report [all/none] clear the list, use none. Use -list report_sel to get a list
of report names.
-report_htmldir directory Specify a directory to contain HTML report output.
-report_htmlstyle Specify how HTML reports are to be split.
[single/alpha/split=N]
-report_htmltitle titlepage Specify the filename of an HTML page you want used
as the title page.
-report_Filename [short/full] Specify whether you want the reports to use short or
full filenames.
-report_time [On/Off] Set to On if you want the time the report was generated
to be placed on the report.
-report_textdir directory Specify a directory to contain text report output.
-report_textfile [Link] Specify a filename for the text report if you are using
the single file option.
-report_textstyle [single/separate] Choose whether you want text reports sent to a single
file or separate files.
-rescan Rescan all the watched directories for newly added or
removed source files.
-rootAdd name1=directory1 [...] Create or reset one or more named root directories. If
the root does not exist in the current project, it is
added. Otherwise, its mapping is reset to the new
directory. A valid name must begin with an uppercase
letter (A-Z) and be followed by at least one more
uppercase letter, numbers, “_”, or “$”. This is a
temporary setting that applies to the current command
only. If you use this option in a [Link] for the
-process option, it applies to multiple commands.

Understand 2.0 User Guide and Reference Manual 13-9

Chapter 13: Command Line Processing

Option Description
-rootList List the defined named root directories.
-rootMode mode Set the current default mode for adding named roots.
-rootRemove name Remove the specified named root definition.
-rootReset name=directory Sets the directory for the specified named root to the
specified directory. If the root does not exist in the
current project, an error occurs. This is a temporary
setting that applies to the current command only.
-snapshot name Create a new snapshot with the specified name.
-snapshotComment "Comment" Associate the specified comment with the snapshot
specified by the -snapshot option.
-version Show the build number of “und” being run.
-vsFile filename Add the specified Visual Studio file to the project
configuration.
-vsFileConf configuration Specify the Visual Studio configuration to use for the
specified -vsFile.
-vsFileDel filename Remove the specified Visual Studio file from this
project.

13-10 Understand 2.0 User Guide and Reference Manual

 Using the understand Command Line

Using the understand Command Line

The Understand 2.0 GUI is launched by the “understand”
executable. Normally, you launch this using the shortcuts provided
by the installation. If you like, you can modify this using the following
command-line syntax.
understand [file_1 ... file_n] [-options]
Any filenames listed on the command like are opened along with
The Understand 2.0 GUI. For example:
understand source.c source.h -db [Link]
The available command-line options (also called command-line
switches) are as follows:

Option Discussion
-contextmenu filename [-line # -col # -text #] Shows the context (right-click) menu for
the specified filename at the mouse
location. Optionally shows the context
menu for the entity located at -line -col
(The -text option provides a name hint for
the entity).
-cwd path Set the current working directory to "path".
This takes precedence over the last
working directory for a project loaded with -
db or -lastproject.
-db filename Open the project specified by the filename.
-existing Detects any running instance of
Understand 2.0 and send the command
line to that instance.
-lastproject Open the last project opened by the
application.
-lastproject_cwd Use the directory of the last opened project
as the current working directory.
-noproject Ignore all project load requests on startup.
(This also clears the "Open Last Project"
application setting.)

Understand 2.0 User Guide and Reference Manual 13-11

Chapter 13: Command Line Processing

Option Discussion
-runAsLicenseLevel level# Specify the license level to use when
running Understand 2.0. Use a level# of 0
for Engineer, 1 for Pro, and 2 for Analyst.
You must be licensed to use the level you
specify.
-visit filename [line# column#] Open the file "filename" in an editor
window. Optionally position the cursor at
the specified line number and column
number in the specified file.

13-12 Understand 2.0 User Guide and Reference Manual

Chapter 14 Quick Reference
This chapter lists of commands provided by Understand 2.0. These
lists provide cross references to information about these commands
in this manual.
Since new versions of Understand 2.0 are provided frequently,
these lists are subject to change and expansion.

This chapter contains the following sections:.

Section Page
File Menu 14–2
Edit Menu 14–2
Search Menu 14–3
Project Menu 14–3
Metrics Menu 14–4
Architect Menu 14–4
Change Menu 14–5
Tools Menu 14–5
Window Menu 14–6
Help Menu 14–7

Understand 2.0 User Guide and Reference Manual 14-1

Chapter 14: Quick Reference

File Menu
The File menu in Understand 2.0 contains the following commands:

Command See
New Project page 3–3
Open Project page 2–5
Convert 1.4 Project page 3–69
Close <project_name> page 2–5
New File page 6–11
Open File page 6–11
Export to Image File page 9–30
Save <filename> page 6–6
Save <filename> As page 6–6
Save All page 6–6
Page Setup page 6–14
Print page 6–14
Print Entity Graph page 9–32
Recent Files page 3–55
Recent Projects page 3–55
Exit page 3–21

Edit Menu
The Edit menu in Understand 2.0 contains the following commands:

Command See
Undo page 6–5
Redo page 6–5
Cut page 6–4
Copy page 6–4
Paste page 6–4

14-2 Understand 2.0 User Guide and Reference Manual

 Project Menu

Search Menu
The Search menu in Understand 2.0 contains the following
commands:

Command See
Entity Filter page 4–5
Entity Locator page 5–3
Find in Files page 5–8
Show Find Results page 5–10
Replace in Files page 5–11
Find page 6–8
Incremental Find page 6–7
Show Favorites page 4–18
Contextual Information Sidebar page 6–9

Project Menu
The Project menu in Understand 2.0 contains the following
commands:

Command See
Configure Project page 3–8
Rescan Watched Project Directories page 3–15
Analyze Changed Files page 3–67
Analyze All Files page 3–67
Project Browser page 4–14
Project Assistant page 4–4
Project Reports page 10–2
Project Interactive Reports page 2–18
Project Graphical Views page 2–18
Project Overview Graphs page 9–2

Understand 2.0 User Guide and Reference Manual 14-3

Chapter 14: Quick Reference

Metrics Menu
The Metrics menu in Understand 2.0 contains the following
commands:

Command See Edition

Project Metrics Summary page 11–3
Browse Project Metrics page 11–4 Analyst & Pro only
Export Project Metrics page 11–6 Analyst & Pro only
Browse Metric Graphs page 11–8 Analyst only
Code Volume page 11–8
File Volume page 11–8
Average Complexity page 11–8 Analyst & Pro only
Sum Complexity page 11–8 Analyst & Pro only

Architect Menu
The Architect menu in Understand 2.0 contains the following
commands:

Command See Edition

Create Custom Architecture page 7–10 Analyst only
Predefined Architectures page 7–10 Analyst & Pro only
Browse Architectures page 7–3
Manage Architectures page 7–9
Filter Architectures page 7–16 Analyst only

14-4 Understand 2.0 User Guide and Reference Manual

 Tools Menu

Change Menu
The Change menu in Understand 2.0 contains the following
commands:

Command See Edition

Make Snapshot page 8–3 Analyst & Pro only
Manage Snapshots page 8–10 Analyst & Pro only
Compare Snapshots page 8–14 Analyst & Pro only
View Reports page 8–27 Analyst only
Compare files/folders page 8–32
Compare Entities page 8–29
Compare arbitrary text page 8–35

Tools Menu
The Tools menu in Understand 2.0 contains the following
commands:

Command See
Run a command page 12–15
User Tools page 12–12
Configure User Tools page 12–3
Record Macro page 6–11
Replay Macro page 6–11
TrackBack History Explorer page 8–36
External Editor Settings page 12–2
Master Scheduler List page 3–19
Scheduled Activities page 3–19
Options page 3–51

Understand 2.0 User Guide and Reference Manual 14-5

Chapter 14: Quick Reference

Window Menu
The Window menu in Understand 2.0 contains the following
commands:

Command See
Last Parse Log page 3–67
Change Dock Window Layout page 5–14
Close <current_file> page 6–6
Close All Document Windows page 5–14
Tile page 5–14
Cascade page 5–14
Split Vertically page 5–14
Split Horizontally page 5–14
<open window list> page 5–14
Editors page 5–14
Entity Graphs page 5–14
Information Browsers page 5–14
Navigator page 5–14
Selector page 5–14
Bookmarks page 6–12

14-6 Understand 2.0 User Guide and Reference Manual

 Help Menu

Help Menu
The Help menu in Understand 2.0 contains the following
commands:

Command See
Help page 1–5
Getting Started page 2–5
Key Bindings page 3–57
Example Projects page 1–5
PERL API Documentation page 2–18
FAQ page 1–5
Run At Licensing Level page 1–3
Licensing page 1–3
View SciTools Blog page 1–5
About Understand page 1–5

Understand 2.0 User Guide and Reference Manual 14-7

Chapter 14: Quick Reference

14-8 Understand 2.0 User Guide and Reference Manual

 Index

Index versions supported, 1–4

Ada category, Project Configuration
dialog, 3–28
-Ada option, und command, 13–5
Symbols
Add found include files to source list field,
" prefixing octal constants or string literals, C++ Includes, 3–35
FORTRAN, 3–41 Add found system include files to source list
"" surrounding normal includes, 3–35 field, C++ Includes, 3–35
# comment in command line file, 13–5 -addDir option, und command, 13–3, 13–5
$ in regular expressions, 5–6 -addDirExcludes option, und command, 13–5
$ prefixing external tool parameters, 12–4, -addDirFilters option, und command, 13–5
12–5 -addDirLangTypes option, und
* in regular expressions, 5–6 command, 13–5
* wild card, 5–6 -addDirSubdirs option, und command, 13–6
+ expanding tree in Info Browser, 4–9 -addDirWatch option, und command, 13–6
+ in regular expressions, 5–6 -addFiles option, und command, 13–3, 13–6
. in regular expressions, 5–6 Adobe Acrobat, saving graphical views
/* ... */ C-style comments, 3–32, 3–41 to, 9–33
: in F77 identifiers, FORTRAN, 3–41 Advanced category, Editor options, 3–63
<> surrounding system includes, 3–35 Alerts category, User Interface options, 3–56
= macro definition in command line, 13–5 Allow Colons in Names field,
? in regular expressions, 5–7 FORTRAN, 3–41
? wild card, 5–6 Allow C-style comments field,
[ - ] in regular expressions, 5–7 FORTRAN, 3–41
[ ] in regular expressions, 5–7 Allow embedded SQL field, Pascal, 3–47
[^ ] in regular expressions, 5–7 Allow function declaration without
\ in regular expressions, 5–7 parentheses field, FORTRAN, 3–41
\< in regular expressions, 5–6 Allow interactivity during intensive processing
\> in regular expressions, 5–6 field, General options, 3–53
^ in regular expressions, 5–6 Allow Nested Comments field, C++, 3–32
| in regular expressions, 5–7 Allow quote in octal constants field,
FORTRAN, 3–41
A Analyst edition, 1–3
About Understand option, Help menu, 1–5 Analyze All Files option, Project menu, 3–20,
absolute portability mode, 3–16 3–67
Activate when Control key is pressed field, Analyze category, Understand Options
Browse Mode Editor options, 3–66 dialog, 3–59
actual parameters, relationship to formal Analyze Changed Files option, Project
parameters, Ada, 3–29 menu, 3–67
Ada -analyze option, und command, 13–4, 13–6
configuration for, 3–28 -analyzeAll option, und command, 13–4, 13–6
macro definitions, 3–30 -analyzeFiles option, und command, 13–4,

Understand 2.0 User Guide and Reference Manual Index–1

 13–6 Architecture Builder, 7–5, 7–13
analyzing projects, 3–67 architecture files, 2–3
after changing configuration of, 3–9 Architecture Graph View, 9–14
beep on completion of, 3–59 architecture templates, 2–3
on command line, 13–4 Architecture Wizard, 7–10, 7–11
scheduling, 3–20 architectures, 2–3, 7–2
and operators, including in strict complexity, auto-architectures, 7–3
Ada, 3–29 changing for Tree View in Changed
angle brackets (<>) surrounding system Entities area, 8–19
includes, 3–35 creating, 7–10
Animate windows/drawers field, User duplicating, 7–5, 7–10
Interface options, 3–54 editing. See Architecture Builder
anti-virus software, turning off while filters for, 7–16
generating reports, 10–4 graphical views of, 7–4, 7–6
%APPDATA% environment variable, 2–6 hierarchies of, exploring, 7–3
Append the names of externally linkable hierarchies of, graphical view of, 9–14
entities with field list of, 7–3
C++, 3–33 listing, 2–14
FORTRAN, 3–42 managing. See Architect Manager
Application font field, General options, 3–52 metrics about, 7–5, 7–7
-arch option, und command, 13–6 metrics graphs about, 11–9
-archDelete option, und command, 13–6 navigating, 2–14
-archExport option, und command, 13–6 predefined, creating architectures
-archImport option, und command, 13–6 from, 7–10
Architect Manager, 7–5, 7–9 renaming, 7–5, 7–10
Architect menu, 14–4 XML listing of, 7–5, 7–15
Browse Architectures option, 7–3 -archRename option, und command, 13–6
Create Custom Architecture option, 7–10 arrows, for Info Browser history, 4–13
Filter Architectures option, 7–17 ASCII text. See text
Manage Architectures option, 7–9 -assembler option, und command, 13–6
New Architecture option, 7–11 -Assembly option, und command, 13–5
Predefined Architectures option, 7–10 Assistant area. See Project Assistant
Architect tool, 2–3 asterisk (*)
Architecture Browser, 2–14, 7–3 in regular expressions, 5–6
duplicating architectures, 7–5, 7–10 wild card, 5–6
graphical views in, 7–4, 7–6 Auto Category, C++ Includes, 3–35
metrics in, 7–5, 7–7 auto-architectures, 2–14, 7–3, 7–4
opening Architect Manager from, 7–5, 7–9 Auto-complete fields, Advanced Editor
opening Architecture Builder from, 7–5 options, 3–64
renaming architectures, 7–5 Automatic compool file field, JOVIAL, 3–45
right-clicking in, 7–4 Average Complexity metrics graph, 11–9
XML listing in, 7–5

Index–2 Understand 2.0 User Guide and Reference Manual

 Index

B reference files, importing, 3–39

versions supported, 1–4
background processing, interactivity
C# category, Project Configuration
during, 3–53
dialog, 3–39
backslash (\) in regular expressions, 5–7
-C# option, und command, 13–5
base classes
C++ category, Project Configuration
count of, 10–25
dialog, 3–32
displaying, 9–10, 9–12, 9–17
-C++ option, und command, 13–5
Base Classes View, 9–10, 9–12
C/C++
beep on parse completion, 3–59
API for custom reports, 2–18, 10–7, 11–2
bitmaps, saving graphical views as, 9–30
configuration for, 3–32
black text, 3–66
include files, auto including, 3–35
Blank metric, 10–27
include files, directories for, 3–34
blocks
include files, ignoring, 3–36
expanding and collapsing, 6–2, 6–10
macro definitions, 3–37
in Filter Area, 2–9
preprocessor directives, 3–37
blue italic text, 3–66
versions supported, 1–4
blue text, 3–65
caching include files, C++, 3–34
bookmarks
Calendar auto-architecture, 2–14, 7–3
creating, 6–12
Called by menu, graphical views, 9–20
list of, 5–15
Called By View, 9–10, 9–12
navigating, 6–12
Calls View, 9–10, 9–11
Bookmarks option, Window menu, 5–15
capitalization, of selected text, 6–11
braces, matching. See brackets
Captured output font field, Command
brackets
Window options, 3–59
in regular expressions, 5–7
caret (^) in regular expressions, 5–6
matching, 6–10
Caret Line field, Editor options, 3–62
Browse Architectures option, Architect
case
menu, 7–3
changing for selected text, 6–11
Browse category, Editor options, 3–66
of displayed entity names, Ada, 3–30
Browse Metric Graphs option, Metrics
of displayed entity names,
menu, 11–2, 11–8
FORTRAN, 3–42
Browse Mode, Source Editor, 3–66, 6–4
of displayed entity names, JOVIAL, 3–46
Browse Project Metrics option, Metrics
of displayed entity names, Pascal, 3–48
menu, 11–2, 11–4
of displayed entity names, PL/M, 3–50
Browser Area, 2–4
of externally linkable entities, Ada, 3–29
Butterfly View, 9–10, 9–11
of externally linkable entities,
Butterfly-Dependency Graph, 7–6, 9–10
FORTRAN, 3–41
of externally linkable entities, Pascal, 3–47
C of identifier names, FORTRAN, 3–41
C# Case of externally linkable entities field
configuration for, 3–39 Ada, 3–29

Understand 2.0 User Guide and Reference Manual Index–3

 FORTRAN, 3–41 declaration for, 9–17
Pascal, 3–47 derived, 9–10, 9–13, 10–25
Case sensitive identifiers field, extended by other classes, 9–10, 9–13,
FORTRAN, 3–41 9–20
case sensitivity extending other classes, 9–10, 9–13, 9–21
of Entity Comparison area, 8–24 as hexagons, in graphical views, 9–18
of FORTRAN identifiers, 3–41 implemented, 9–21
CBO (Count of Coupled Classes) implemented by, 9–21
metric, 10–25 information about, 9–14
Change Case menu option, 6–11 inherited from other classes, 9–10
Change Log, 3–2, 10–19 listing in Filter Area, 2–9
Change menu, 14–5 metrics about, 10–24, 10–25
Compare arbitrary text option, 8–35 providing without source code, Java, 3–44
Compare Entities option, 8–31 reports about, 10–11, 10–15, 10–24, 10–25
Compare files/folders option, 8–32 -classpath option, und command, 13–6
Compare Snapshots option, 8–14 clipboard, 8–23
Make Snapshot option, 3–20, 8–3 copying graphical view to, 9–30
Manage Snapshots option, 8–2, 8–10 copying text from Source Editor to, 6–4
Change Results window, 8–17 Close All Document Windows option,
Changed Entities area, 8–18 Window menu, 6–6
HTML reports of, 8–27 Close option
Changed Entities area, Change Results File menu, 2–6
window, 8–17, 8–18 Window menu, 6–6
-changeReportDir option, und Close Selected Window(s) command, 5–15
command, 13–6 Code metric, 10–27
character strings, red text for, 3–65 Code Volume metrics graph, 11–9
Child Lib Units View, 9–10 cohesion for class data members, 10–25
children of entity, 9–10 colon (:) in F77 identifiers, FORTRAN, 3–41
CIS. See Contextual Information Sidebar Color Mode field, Advanced Editor
Class and Interface Cross-Reference options, 3–64
report, 10–11 colors
Class Declaration View, 9–14, 9–17 for Changed Entities area, 8–20
Class Extend Tree report, 10–15 in Entity Comparison area, 8–25
.class files, 3–44 in file/folder comparisons, 8–33
Class Inheritance View, 9–10 of highlighted differences in Entity
Class Metrics report, 10–24 Comparison area, 8–23
Class OO Metrics report, 10–25 of merged differences in Difference List
Class Paths category, Java, 3–44 area, 8–26
classes of merged differences in Entity
base classes for, 9–10, 9–12, 9–17, 10–25 Comparison area, 8–26
cohesion of, 10–25 for printing source code, 3–64
coupled, 10–25 of rows in User Interface, alternating, 3–54

Index–4 Understand 2.0 User Guide and Reference Manual

 Index

in Source Editor, customizing, 6–2, 3–65 -compiler_includepath option, und

in Source Editor, default, 3–65 command, 13–6
column truncation -compiler_name option, und command, 13–6
FORTRAN, 3–41 -compiler_version option, und
JOVIAL, 3–45 command, 13–6
command line. See und command; complexity
understand command exception handlers included in, Ada, 3–29
command renames, reports about, 10–17 FOR-loops included in, Ada, 3–29
Command window, 12–16 metrics graphs about, 11–9
Command Window category, Understand strict, and/or operators in, Ada, 3–29
Options dialog, 3–59 Component field, Key Bindings options, 3–57
commands, external. See external tools compool file, JOVIAL, 3–45
Comment metric, 10–27 Configure category, Understand Options
comments dialog, 3–59
adding or removing, 6–10 Configure option, Project menu, 3–8
associating with entities, Ada, 3–30 Configure User Tools option, Tools
associating with entities, C++, 3–33 menu, 12–3, 12–14
associating with entities, Java, 3–43 constants
blue italic text for, 3–66 displayed in graphical views, 9–20
C-style, 3–32 reports about, 10–21
nested, C++, 3–32 Constants menu, graphical views, 9–20
Compaq Pascal, 3–47 contact information, 1–4
Compare arbitrary text option, Change Context Browser, Contextual Information
menu, 8–35 Sidebar, 6–9
Compare Entities option, Change -contextmenu option, understand
menu, 8–31 command, 13–11
Compare files/folders option, Change Contextual Information Sidebar (CIS), 6–9
menu, 8–32 Control Flow View, 9–14, 9–17
Compare Snapshots option, Change Convert 1.4 Project option, File menu, 3–69
menu, 8–14 !COPY directives, directories to search,
compilation environment, Ada, 3–29 JOVIAL, 3–46
compilation unit Copy category, JOVIAL, 3–46
Child Library Units of, 9–10 Copy option, Edit menu, 6–4
declaration nesting of program units copying text, 8–23
in, 9–10 Count and/or operators in strict complexity
entities called by, 9–10 field, Ada, 3–29
instantiation tree for, 9–10 Count exception handlers in complexity field,
With By relationships of, 9–11, 9–29 Ada, 3–29
With relationships of, 9–11 Count for-loops in complexity field, Ada, 3–29
Compiler field, C++, 3–32 Count of All Methods metric, 10–25
Compiler Include Paths field, C++, 3–32 Count of Base Classes metric, 10–25
compiler, compared to Understand, 3–2 Count of Coupled Classes metric, 10–25

Understand 2.0 User Guide and Reference Manual Index–5

Count of Derived Classes metric, 10–25 -cwd option
Count of Instance Methods metric, 10–25 und command, 13–7
Count of Instance Variables metric, 10–25 understand command, 13–11
Count of Methods metric, 10–25 Cyclomatic complexity, 10–18, 10–27
coupled classes, 10–25
Create and cross-reference record object D
components field, Ada, 3–29 dashed outline shapes, in graphical
Create Custom Architecture option, Architect views, 9–18
menu, 7–10 Data Dictionary report, 10–8
Create implicit special member functions Data Members View, 9–14
field, 3–33 database, 2–3, 3–2
-create option, und command, 13–3, 13–6 changes to format of, 3–2
Create references in inactive code field, creating on command line, 13–2, 13–3
C++, 3–33 file extension for, 2–3, 3–2
Create references to local objects field, multi-user read/write access for, 3–2
C++, 3–33 See also project
Create references to macros during macro -db option
expansion field, C++, 3–33 und command, 13–2, 13–3, 13–5
Create references to parameters field, understand command, 13–11
C++, 3–33 DEC Pascal, 3–47
Create relations between formal and actual $Decl variables, 12–4, 12–5
parameters field, Ada, 3–29 Declaration File View, 9–14, 9–16
Crossing layout option, 9–23 Declaration Tree report, 10–14
cross-reference reports, 10–8 Declaration Tree View, 9–10
cross-referencing record object components, Declaration Type View, 9–14, 9–16
Ada, 3–29 Declaration View, 9–14, 9–15
C-style comments declaration views
in FORTRAN, 3–41 calling methods displayed in, 9–20
nesting of, allowing, 3–32 constants displayed in, 9–20
CSV file, exporting metrics to, 3–20, 11–2, default members displayed in, 9–20
11–6 extended by classes displayed in, 9–20
Ctrl+Alt+F keystroke, find and replace extended classes displayed in, 9–21
text, 6–8 external functions displayed in, 9–21
Ctrl+F keystroke, find text, 6–7 file dependencies displayed in, 9–20
Ctrl+j keystroke, jump to matching globals displayed in, 9–21
bracket, 6–10 header files include by’s displayed, 9–22
Ctrl+right-click keystroke implemented by classes displayed
creating new windows, 2–7, 4–2 in, 9–21
Ctrl+Shift+j keystroke, select text in implemented classes displayed in, 9–21
brackets, 6–10 imported entities displayed in, 9–22
$Cur variables, 12–4, 12–5 include files displayed in, 9–22
Cut option, Edit menu, 6–4 inherited entities displayed in, 9–22

Index–6 Understand 2.0 User Guide and Reference Manual

 Index

invocations displayed in, 9–23 deleting from project, 3–14

local items displayed in, 9–24 overriding settings for, 3–14
members displayed in, 9–25 watched, scanning, 3–15, 3–20
objects displayed in, 9–25 watched, setting, 3–13, 3–14
operators displayed in, 9–25 Display entity names as field
private members displayed in, 9–26 Ada, 3–30
protected members displayed in, 9–26 FORTRAN, 3–42
public members displayed in, 9–26 JOVIAL, 3–46
rename declarations in, 9–26 Pascal, 3–48
static functions displayed in, 9–27 PL/M, 3–50
types displayed in, 9–28 DIT (Max Inheritance Tree) metric, 10–25
used-by items shown in, 9–29 Dock Window Layouts field, User Interface
variables displayed in, 9–29 options, 3–55
With By relationships displayed in, 9–29 docking windows, 2–2
With relationships displayed in, 9–29 Document Area, 2–4
See also graphical views documentation, 1–5, 2–6
declarations dollar sign ($)
implicit, report about, 10–20 in regular expressions, 5–6
local, including in database, C++, 3–33 prefixing external tool parameters, 12–4,
Declared In View, 9–10 12–5
Default Members menu, graphical DOS line termination style
views, 9–20 for reports, 10–4
Default most recently used list setting field, for saving source files, 3–62
User Interface Lists options, 3–55 double quotes. See quotes
Default style field, Editor options, 3–61 double-click merging, in Entity Comparison
default working directory, 3–53 area, 8–25, 8–26
-define option, und command, 13–7 double-clicking
defines. See macros in Bookmarks area, 6–12
Delphi Pascal, 3–47 column header dividers, 5–3
dependencies, file, 9–20 entities in Entity Filter, 4–11
Dependency Graph, 7–4, 7–6, 9–10 entities in graphical view, 9–6
Dependent menu, graphical views, 9–20 entities in Info Browser, 4–11
Dependent Of menu, graphical views, 9–20 in Exploring View, 4–16
derived classes, 9–10, 9–13, 10–25 in Favorites area, 4–18
Derived Classes View, 9–10, 9–13 in Find Results window, 5–10
Difference List area, Change Results messages in Parse Log window, 3–68
window, 8–17, 8–26 in Navigator list of open windows, 5–14
directives, C++, 3–37 in Project Browser, 11–4
directories in Source Editor, 2–13
adding to project, 3–12 drawers, 2–2, 3–54
comparing, 8–32 drop-down menu See right-clicking
copying, 8–34 .dsp file extension, 3–26

Understand 2.0 User Guide and Reference Manual Index–7

.dsw file extension, 3–26 listed in Entity Locator, 2–10, 5–3
Duplicate Architecture menu option, 7–5 listed in Filter Area, 2–9
duplicate references, C++, 3–33 metrics for. See metrics
Duplicate Subtrees menu, graphical names of, formatting for reports, 3–25
views, 9–20 as rectangles, in graphical views, 9–18
references for, 4–12
E relationships between, 2–3
Edit Architecture menu option, 7–5, 7–13 renamed, 9–14
Edit Graphic Filters menu option, 9–8 reports about. See reports
Edit menu, 14–2 sorting of, 4–5
Copy option, 6–4 structural information about, graphical
Cut option, 6–4 view of, 9–5, 9–14
editions of Understand, 1–3 unknown, 9–28
Editor category, Understand Options unresolved, 9–29
dialog, 3–61 XML listing of, 7–5
editor windows, saving automatically, 3–52 See also specific entities
editor, external, 12–2 Entity Comparison area, Change Results
editor, source. See Source Editor window, 8–17, 8–22
Emacs editor, 12–2, 12–3 Entity Filter, 4–5
embedded SQL, in Pascal, 3–47 displaying information about entities
encoding formats, 3–18, 3–61 in, 4–8
Engineer edition, 1–3 displaying source of selected entity, 4–11
entities, 2–3 entities not listed in, 2–10, 5–3
changes in, between snapshots, 8–18 jumping to entities in, 2–9
comments associated with, Ada, 3–30 location of, 2–4
comments associated with, Java, 3–43 right-clicking in, 2–8
comparing two entities, 8–31 Entity Graphs option, Window menu, 9–6
comparisons between snapshots of, 8–29 entity index, for HTML reports, 10–5
comparisons between versions of, 8–22 Entity Locator, 2–10, 5–3
components of, 9–14 column headers in, customizing, 5–4
current, information about, 6–9 columns in, hiding and reordering, 5–4
declaration structure for, 9–14, 9–15 columns in, resizing, 5–3
displaying source for. See Source Editor filtering by selection, 5–5
favorites of, displaying, 4–18 filtering manually, 5–6
favorites of, marking, 4–17 filtering with regular expressions, 5–6
full name of, displaying, 4–6 filtering with wildcards, 5–6
graphical views of. See graphical views length of names in, 5–3
hierarchy of, exploring, 4–16, 6–9 opening, 5–3
hierarchy of, graphical view, 9–5, 9–10 right-clicking in, 2–10, 5–3
information about. See Info Browser right-clicking on column header, 5–4, 5–6
list of, alphabetic, 10–8 right-clicking on entities, 5–5
listed in Entity Filter, 4–5 sorting entities in, 5–4

Index–8 Understand 2.0 User Guide and Reference Manual

 Index

Entity Locator option, Search menu, 2–10, configuring, 12–3

5–3 editor, 12–2
entity_index.html file, 10–5 externally linkable entities
environment variables case of, Ada, 3–29
initialization file location, 2–6 case of, FORTRAN, 3–41
using in include paths, C++, 3–34 case of, Pascal, 3–47
equal sign (=) in macro definition in command prefix for, C++, 3–33
line, 13–5 prefix for, FORTRAN, 3–41
errors suffix for, C++, 3–33
displaying from Parse Log window, 3–68 suffix for, FORTRAN, 3–42
parse errors, prompting for, Ada, 3–30 Externally Modified Files field, Editor
parsing, FORTRAN, 3–42 options, 3–62
Essential metric, 10–27
Example Projects option, Help menu, 1–5 F
Exception Cross-Reference report, 10–13 F5 key, Find in Files option, 5–8
exceptions FAQ option, Help menu, 1–5, 2–18
handlers for, including in Ada favorites, 2–11
complexity, 3–29 displaying, 4–18
reports about, 10–13 marking entities as, 4–17
-existing option, understand toolbar for, 5–15
command, 13–11 Favorites option, Search menu, 2–11
Exploring view, 4–16 File Average Metrics report, 10–27
Export Project Metrics option, Metrics File Contents report, 10–10
menu, 3–20, 11–2, 11–6 file extensions
exporting tool commands, 12–14 configuring for project, 3–17
Extended By menu, graphical views, 9–20 for database, 2–3, 3–2
Extended By View, 9–10, 9–13 for MSVC project files, 3–26
Extends menu, graphical views, 9–21 File Information, Contextual Information
Extends View, 9–10, 9–13 Sidebar, 6–9
extensions. See file extensions File menu, 14–2
external editor, 12–2 Close option, 2–6
External Editor Settings option, Tools Convert 1.4 Project option, 3–69
menu, 12–2 New File option, 6–11
External Functions menu, graphical New Project option, 3–3, 3–4
views, 9–21 Open File option, 6–11
external tools Open Project option, 2–6
adding to Right-click Menu, 12–4, 12–10 Page Setup option, 6–14
adding to toolbar, 12–13 Print Entity Graph option, 9–32
adding to User Tools menu, 12–12 Print option, 6–14
commands for, importing and Recent Projects option, 2–6
exporting, 12–14 Save All option, 6–6
commands for, running, 12–15 Save option, 6–6

Understand 2.0 User Guide and Reference Manual Index–9

File Metrics report, 10–26 Find Results window, 2–11, 5–10
File Mode field, Editor options, 3–61 fixed file format, FORTRAN, 3–41
File Options category, Project Configuration flow chart symbols, 9–18
dialog, 3–18 flow charts, 9–14, 9–17
File Types category, Project Configuration fold icon, 8–18
dialog, 3–17 folders. See directories
File Volume metrics graph, 11–9 font
Filename menu, graphical views, 9–21 in Command window, changing, 3–59
filenames for printing source code, 3–64
in graphical views, 9–21 for Source Editor windows, 3–61
for reports, 10–5 in Understand, changing, 3–52
in title areas, 3–55 Font Size field, Advanced Editor
files options, 3–64
comparing, 8–32 FOR-loops, including in complexity metrics,
copying, 8–34 Ada, 3–29
Info Browser for, 6–9 formal parameters, relationship to actual
location included in listing of, 4–6 parameters, Ada, 3–29
searching, 2–11, 5–8 Format field, FORTRAN, 3–41
searching and replacing in, 5–11 FORTRAN
toolbar for, 5–15 configuration for, 3–40
tracking changes to, 8–36 extensions supported, 1–4
See also database; header files; include include files, 3–42
files; MSVC project; project; source files macro definitions, 3–42
Files category, Project Configuration reports showing non-standard extension
dialog, 3–11 usage, 10–19
Filesystem auto-architecture, 2–14, 7–3 versions supported, 1–4
-fileType option, und command, 13–7 FORTRAN category, Project Configuration
-fileTypeDel option, und command, 13–7 dialog, 3–40
Filter Architectures option, Architect FORTRAN Extension Usage report, 10–19
menu, 7–17 -Fortran option, und command, 13–5
Filter Area, 2–9 frames in windows, sliding, 2–2
See also Entity Filter; Project Browser free file format, FORTRAN, 3–41
Filter By Selection menu option, 5–5 function declarations without parentheses,
Filter field, Entity Filter, 4–6 FORTRAN, 3–41
filters Function Pointer menu, graphical
for architectures, 7–16 views, 9–21
for graphical views, 9–8 Functional Decomposition predefined
See also Entity Filter; Entity Locator architecture, 7–10
Find dialog, 6–8 functions
Find in Files dialog, 2–4, 2–11 external, 9–21
Find in Files menu option, 2–11, 5–8 in graphical views, 9–26
Find option, Search menu, 6–8 listing in Filter Area, 2–9

Index–10 Understand 2.0 User Guide and Reference Manual

 Index

metrics about, 10–27 fullnames displayed in, 9–25

reports about, 10–9, 10–10, 10–27 function pointers displayed in, 9–21
static, 9–27 functions displayed in, 9–26
See also invocations; procedures; globals displayed in, 9–21
program units Graph View of, 9–3
header files include by’s displayed, 9–22
G hierarchy levels displayed in, 9–24
General category, Understand Options hierarchy views, 9–5, 9–10
dialog, 3–52 implemented by classes displayed
Generic Instantiation report, 10–17 in, 9–21
generic unit implemented classes displayed in, 9–21
instantiation hierarchy for, 9–10 imported entities displayed in, 9–22
instantiation tree for, 9–10 include files displayed in, 9–22
Getting Started dialog inherited entities displayed in, 9–22
displaying at startup, 3–52 intrinsic functions displayed in, 9–22
opening, 2–6 invocations displayed in, 9–23
Getting Started option, Help menu, 1–5, 2–6 layout configuration for, 9–7, 9–19, 9–23
Getting Started tab, 2–5 local items displayed in, 9–24
Globals menu, graphical views, 9–21 members displayed in, 9–25
Go To Line dialog, 6–4 multiple subtrees displayed in, 9–20
Graph Architecture, 7–4, 7–6 objects displayed in, 9–25
Graph View of graphs, 9–3 open, list of, 9–6
Graph View, for metrics graphs, 11–10 operators displayed in, 9–25
Graphic Filter dialog, 9–8 parameters, displaying in, 9–26
graphical user interface (GUI), parts of, 2–4 path highlighting in, 9–7
graphical views, 2–16, 9–2 printing, 9–7, 9–32
of architecture, 7–4, 7–6 private members displayed in, 9–26
browsing, 9–6 procedures displayed in, 9–26
calling methods displayed in, 9–20 protected members displayed in, 9–26
constants displayed in, 9–20 public members displayed in, 9–26
copying to clipboard, 9–30 rename declarations in, 9–26
default members displayed in, 9–20 reusing, 3–53, 9–9
diagram of, 2–4 saving, 9–7, 9–30
displaying, 9–4 saving as PDF, 9–33
entity name truncation for, 9–28 scrolling in, 9–6
expanding or contracting nodes in, 9–6 sorting entities in, 9–27
extended by classes displayed in, 9–20 spacing entities in, 9–27
extended classes displayed in, 9–21 SQL entities shown in, 9–27
external functions displayed in, 9–21 static functions displayed in, 9–27
file dependencies displayed in, 9–20 structure views, 9–5, 9–14
filename display options, 9–21 synchronizing with other windows, 9–9
filtering, 9–8 Table View of, 9–3

Understand 2.0 User Guide and Reference Manual Index–11

 text size of, 9–27 parameters, displaying in, 9–26
types displayed in, 9–28 See also graphical views
unknown entities, displaying, 9–28 highlighting full line at cursor, 3–62
unresolved entities, displaying, 9–29 history
used-by items shown in, 9–29 Info Browser, 4–9, 4–13
uses items shown by, 9–29 snapshots, 8–30
variables displayed in, 9–29 Source Editor, 6–8
With By relationships displayed in, 9–29 toolbar for, 5–15
With relationships displayed in, 9–29 TrackBack for files, 6–4, 8–36
zooming, 9–7 Horizontal Non-Crossing layout option, 9–24
See also structure views; hierarchy views HTML
Graphical Views menu option, 7–4, 7–6, 9–4 Change Results reports as, 8–27
graphs, of metrics, 11–8 entity index in reports, 10–5
gray background for text, 3–66 exporting metrics to, 3–21, 11–2, 11–5
gray shapes, in graphical views, 9–18 generating reports as, 2–17, 3–24, 10–2,
green text, 3–66 10–4
GUI (graphical user interface), parts of, 2–4 viewing reports as, 10–5
GVIM editor, 12–2 Hyper Grep. See Find in Files dialog
hyphen (-) collapsing tree in Info
H Browser, 4–9
header files, 9–22
help, 1–5, 2–6 I
Help menu, 14–7 IB. See Info Browser
About Understand, 1–5 IFANIN (Count of Base Classes)
Example Projects option, 1–5 metric, 10–25
FAQ option, 1–5, 2–18 Ignore category, C++ Includes, 3–36
Getting Started option, 1–5, 2–6 Implementation fields field, JOVIAL, 3–45
Help option, 1–5 Implemented By menu, graphical
Key Bindings option, 1–5, 6–11 views, 9–21
Perl API Documentation option, 1–5, 2–18, Implements menu, graphical views, 9–21
11–2 implicit special member functions, C++, 3–33
Run at License Level option, 1–3 Implicitly Declared Objects report, 10–20
View SciTools Blog option, 1–5 Import report, 10–17
-help option, und command, 13–2, 13–7 imported entities, displaying in graphical
hexagons, in graphical views, 9–18 views, 9–22
hiding common lines, in Entity Comparison importing tool commands, 12–14
area, 8–25 Imports menu, graphical views, 9–22
hierarchy views, 2–16, 9–5 inactive code, cross-reference information
layout of, 9–23 for, C++, 3–33
list of, 9–10 Include By View, 9–12
multiple subtrees displayed in, 9–20 Include File Cross-Reference report, 10–12
number of levels in, 9–24 include files

Index–12 Understand 2.0 User Guide and Reference Manual

 Index

adding as source files, C++, 3–34 copying information in, 4–8, 4–13
adding as source files, FORTRAN, 3–42 displaying from entity in Entity Filter, 4–8
adding as source files, PL/M, 3–50 displaying source of selected entity, 4–11
adding before each project file, C++, 3–35 entity information displayed by,
adding in bulk, C++, 3–35 choosing, 4–10
adding in bulk, FORTRAN, 3–42 expanding and collapsing the tree, 4–9
adding in bulk, PL/M, 3–50 for current entity, 6–9
adding to project, C++, 3–34 for current file, 6–9
adding to project, FORTRAN, 3–42 history for, 4–9, 4–13
adding to project, PL/M, 3–50 location of, 2–4
compiler path for, C++, 3–32 metrics in, 4–12, 11–2
displayed in graphical views, 9–22 multiple occurrences open, 4–11
environment variables in paths for, References in, 4–12
C++, 3–34 right-clicking in, 2–8
hierarchy of, for source files, 9–10, 9–12 saving information in, 4–8, 4–13
ignoring during analysis, C++, 3–36 searching, 4–10
overriding MSVC project settings for, 3–27 synchronizing, 4–11
replacement text for, C++, 3–36 Inherited By menu, graphical views, 9–22
replacement text for, FORTRAN, 3–42 Inherits menu, graphical views, 9–22
reports about, 10–12 initialization files, 2–6
system include files, C++, 3–35 Insert Spaces Instead of Tabs field, Editor
-include option, und command, 13–7 options, 3–62
Include View, 9–10, 9–12 instance methods, 10–25
-include_addfound option, und instance variables, 10–25
command, 13–7 Instantiated From View, 9–10
-include_addfoundsys option, und instantiation
command, 13–7 of compilation units, 9–10
-include_case option, und command, 13–7 of generic types, 9–10
-include_search option, und command, 13–7 of generic units, 9–10
-include_treatsys option, und reports about, 10–17
command, 13–7 Instantiations View, 9–10
IncludeBy View, 9–10 interactivity during background
Included By menu, graphical views, 9–22 processing, 3–53
Includes category interfaces
C++, 3–34 listing in Filter Area, 2–9
FORTRAN, 3–42 reports about, 10–11
PL/M, 3–50 interrupt handlers, listed as unused program
Includes menu, graphical views, 9–22 units, 10–22
Incremental Find option, Search menu, 6–7 intrinsic functions, parsing, FORTRAN, 3–41
Indent field, Editor options, 3–62 Intrinsic menu, graphical views, 9–22
Info Browser (IB), 2–9, 2–12, 4–8 Intrinsics file field, FORTRAN, 3–41
architecture information in, 7–3 Invocation Tree report, 10–16

Understand 2.0 User Guide and Reference Manual Index–13

Invocation View, 9–10 -lastproject option, understand
invocations command, 13–11
reports about, 10–16 -lastproject_cwd option, understand
views of, 9–10, 9–11, 9–12, 9–14, 9–15 command, 13–11
Invocations menu, graphical views, 9–23 Layout menu, graphical views, 9–23
layout, for graphical views, 9–23
J LCOM (Percent Lack of Cohesion)
.jar files, 3–44 metric, 10–25
Java Less memory usages versus speed field,
configuration for, 3–43 Ada, 3–30
versions supported, 1–4 Level menu, graphical views, 9–24
Java category, Project Configuration libraries, standard
dialog, 3–43 Ada, directory for, 3–29
-Java option, und command, 13–5 including in parse log, 3–59
JDK, versions supported, 1–4 Pascal, paths for, 3–49
JNI external entities, Java, 3–43 licensing, 1–3
JOVIAL specifying level from command line, 13–12
configuration for, 3–45 specifying level from Help menu, 1–3
directories for !COPY directives, 3–46 line endings for source files, 3–61
versions supported, 1–4 line numbers, displaying in Source
JOVIAL category, Project Configuration Editor, 6–2
dialog, 3–45 line termination style
-Jovial option, und command, 13–5 for reports, 10–4
JPEG format, saving graphical views for saving source files, 3–62
as, 9–30 Lines metric, 10–27
@[Link] file, 13–5
K -list option, und command, 13–2, 13–7
List view, Changed Entities area, 8–21
Key Bindings category, Understand Options
-list_tersemode option, und command, 13–7
dialog, 3–57, 6–11 -listarch option, und command, 13–7
Key Bindings option, Help menu, 1–5, 6–11
-listfiles option, und command, 13–7
keyboard mappings, 3–57
-listfilestree option, und command, 13–7
Keyboard Scheme field, Key Bindings Lists category, User Interface options, 3–55
options, 3–57
Local menu, graphical views, 9–24
keywords, blue text for, 3–65
local object declarations, including in
KNI external entities, Java, 3–43 database, C++, 3–33
local parameters, listed in Entity
L Locator, 2–10
Language auto-architecture, 2–14, 7–4
Languages category, Project Configuration M
dialog, 3–10 Macintosh line termination style, 3–62
-languages option, und command, 13–7
Macro Cross-Reference report, 10–12

Index–14 Understand 2.0 User Guide and Reference Manual

 Index

macros members
adding in bulk, C++, 3–38 cohesion of, 10–25
changing, Ada, 3–31 default, 9–20
compiler-specific, C++, 3–32 displayed in graphical views, 9–25
defining in command line, 13–5 graphical views of, 9–14
defining on command line, Ada, 3–31 private, 9–26
defining, Ada, 3–30 protected, 9–26
defining, C++, 3–37 public, 9–26
of editing changes, recording and Members menu, graphical views, 9–25
replaying, 6–11 memory
expansion text for, C++, 3–34 caching include files, C++, 3–34
importing, Ada, 3–31 optimizing analysis to use less, Ada, 3–30
listing in Filter Area, 2–9 menu bar, 2–4
as octagons, in graphical views, 9–18 menus. See specific menus
overriding MSVC project settings for, 3–27 merging, in Entity Comparison area, 8–25
recording references when expanding, methods
C++, 3–33 cohesion of, 10–25
reports about, 10–10, 10–12 instance, 10–25
undefined, C++, 3–38 listing in Filter Area, 2–9
See also objects metrics about, 10–25
Macros category metrics, 7–5, 7–7
Ada, 3–30 calculating automatically, 3–20
C++, 3–37 configuring, 3–22
FORTRAN, 3–42 displayed in Info Browser, 4–12
Pascal, 3–48 exporting to CSV file, 3–20, 11–2, 11–6
Main subprograms field, Ada, 3–30 exporting to HTML, 3–21, 11–2, 11–5
maintain_uperl command, 2–4 for project, 11–3, 11–4
Make Snapshot option, Change menu, 3–20, graphs for, 11–8
8–3 in Info Browser, 11–2
Manage Architectures menu option, 7–5 list of, online, 10–18, 10–23, 11–3
Manage Architectures option, Architect reports about, 10–23, 10–24, 10–25, 10–26,
menu, 7–9 10–27, 11–2
Manage Snapshots option, Change selecting, 3–23
menu, 8–2, 8–10 Metrics category, Project Configuration
Margins field, Editor options, 3–63 dialog, 3–22
Master Scheduler List option, Tools Metrics Export, 7–5
menu, 3–21 Metrics Export menu option, 7–8
"Mastering Regular Expressions" Metrics menu, 14–4
(O’Reilly), 5–7 Browse Metric Graphs option, 11–2, 11–8
Max Inheritance Tree metric, 10–25 Browse Project Metrics option, 11–2, 11–4
McCabe (Cyclomatic) complexity, 10–18, Export Project Metrics option, 3–20, 11–2,
10–27 11–6

Understand 2.0 User Guide and Reference Manual Index–15

 Project Metrics Summary option, 11–2, New Project Wizard, 3–4, 3–59
11–3 next button, 2–2
-metrics option, und command, 13–8 Next icon, 2–13
Metrics Summary, 7–5, 7–7 NIM (Count of Instance Methods)
-metrics_DeclFilename option, und metric, 10–25
command, 13–8 NIV (Count of Instance Variables)
-metrics_Filename option, und metric, 10–25
command, 13–8 No Truncation text option, 9–28
-metrics_Parameters option, und No Wrap text option, 9–28
command, 13–8 NOC (Count of Derived Classes)
-metrics_sel option, und command, 13–8 metric, 10–25
-metrics_Titles option, und command, 13–8 -noproject option, understand
Microsoft Visio files, saving graphical views command, 13–11
as, 9–30
Microsoft Visual C++ project. See MSVC O
project Object Cross-Reference report, 10–10
Microsoft Visual C++, as editor, 12–2 object-oriented metrics, 10–25
minus sign (-) collapsing tree in Info objects
Browser, 4–9 displayed in graphical views, 9–25
Modified metric, 10–27 listing in Project Window, 2–9
modules, listing in Filter Area, 2–9 reports about, 10–10, 10–21
MSVC project, importing into Understand Objects menu, graphical views, 9–25
project, 3–5, 3–26 octagons in graphical views, 9–18
multiple users, initialization files for, 2–6 -odefine option, und command, 13–8
-oinclude option, und command, 13–8
N online help, 1–5, 2–6
Name menu, graphical views, 9–25 Open File option, File menu, 6–11
Named from Alternate Source Location Open last project at startup field, General
snapshot, 8–3, 8–6 options, 3–53
Named from Any Point in Time Open Project option, File menu, 2–6
snapshot, 8–3, 8–9 Operators menu, graphical views, 9–25
Named from Current Database operators, displayed in graphical views, 9–25
snapshot, 8–3, 8–5 -option_Cache option, und command, 13–8
named root portability mode, 3–16 -option_RefMacroExpand option, und
named roots, 3–60 command, 13–8
Namespaces category, Pascal, 3–48 -option_Save_Comments option, und
Navigator option, Window menu, 5–14 command, 13–8
nested comments, C++, 3–32 Options option, Tools menu, 3–51
New Architecture option, Architect Options subcategory, Reports, 3–25
menu, 7–11 or operators, including in strict complexity,
New File option, File menu, 6–11 Ada, 3–29
New Project option, File menu, 3–3, 3–4 Output subcategory, Reports, 3–24, 10–2

Index–16 Understand 2.0 User Guide and Reference Manual

 Index

-override option, und command, 13–8 patching lines of context, in Entity

Comparison area, 8–25, 8–26
P path highlighting, in graphical views, 9–7
Package View, 9–14 pattern matching. See regular expressions
packages PC line termination style
declaration structure for, 9–14 for reports, 10–4
listing in Filter Area, 2–9 for saving source files, 3–62
reports about, 10–17 .pcn file, 10–10
With By relationships for, 9–14 PDF, saving graphical views to, 9–33
With relationships for, 9–14 Percent Lack of Cohesion metric, 10–25
page guide, showing, 3–63 period (.) in regular expressions, 5–6
Page Setup option, File menu, 6–14 Perl
parallelograms, in graphical views, 9–18 interface for custom reports, 2–18, 10–7,
parameters 11–2
cross-reference information for, C++, 3–33 scripts, 2–4
relationships between formal and actual, Perl API Documentation option, Help
Ada, 3–29 menu, 1–5, 2–18, 11–2
reports about, 10–10, 10–20, 10–21 pin icons. See pushpin icons
See also objects pink background for text, 3–66
Parameters menu, graphical views, 9–26 PL/M
parent configuration for, 3–50
of class. See base classes versions supported, 1–4
of entity, 9–10 PL/M category, Project Configuration
Parent Declaration View, 9–14, 9–15 dialog, 3–50
Parent Lib Unit View, 9–10 -Plm option, und command, 13–5
parentheses, matching. See brackets plus sign (+)
Parse Log window, 3–68 expanding tree in Info Browser, 4–9
reopening previous Parse Log, 5–14 in regular expressions, 5–6
saving to text file, 3–68 PNG format, saving graphical views as, 9–30
parsing. See analyzing projects Popup Menu category, Tool Configurations
Pascal dialog, 12–10
configuration for, 3–47 Portability category, Understand Options
macro definitions, 3–48 dialog, 3–60
namespaces directory, 3–48 portability of project, 3–16
search paths, 3–49 pound sign (#) comment in command line
standard libraries, paths for, 3–49 file, 13–5
versions supported, 1–4 pragma statements, defining macros
Pascal category, Project Configuration referenced in, Ada, 3–30
dialog, 3–47 Predeclared entities file field, Pascal, 3–47
-Pascal option, und command, 13–5 Predefined Architectures option, Architect
Patch File area, Change Results menu, 7–10
window, 8–17, 8–26 Prepend the names of externally linkable

Understand 2.0 User Guide and Reference Manual Index–17

 entities with field analyzing (parsing). See analyzing
C++, 3–33 projects
FORTRAN, 3–41 closing, 2–6
Prepend the names of JNI/KNI external closing automatically when opening new
entities with field, Java, 3–43 project, 3–56
preprocessor directives, C++, 3–37 configuring, 3–8
Preprocessor field, Ada, 3–28 converting from Understand 1.4 to
preprocessor macros. See macros 2.0, 3–69
preprocessor statements, green text creating, 3–3
for, 3–66 creating on command line, 13–3
preprocessor support, enabling, creating, with New Project Wizard, 3–59
FORTRAN, 3–41 directory hierarchy for, displaying, 4–14
previous button, 2–2 existing, opening, 2–5
Previous icon, 2–13 metrics for, 10–24, 11–3, 11–4
Print Entity Graph option, File menu, 9–32 opening most-recent project at
Print option, File menu, 6–14 startup, 3–53
printing portability of, 3–16
graphical views, 9–32 saving configuration of, 3–9
source files, 6–14, 9–32 snapshots of. See snapshots
Private Members menu, graphical toolbar for, 5–15
views, 9–26 Project Assistant, 4–4
Pro edition, 1–3 Project Assistant option, Project menu, 4–4
procedures Project Browser, 4–14
in graphical views, 9–26 Project Browser option, Project menu, 4–14
reports about, 10–9 Project Configuration dialog, 3–8, 10–2
See also invocation; functions; program Ada category, 3–28
units C# category, 3–39
-process option, und command, 13–8 C++ category, 3–32
Program Unit Complexity report, 10–18 File Options category, 3–18
Program Unit Cross-Reference report, 10–9 File Types category, 3–17
Program Unit Metrics report, 10–25 Files category, 3–11
program units FORTRAN category, 3–40
metrics about, 10–25 Java category, 3–43
reports about, 10–14, 10–16, 10–17, 10–18, JOVIAL category, 3–45
10–22, 10–25 Languages category, 3–10
With relationships for, 10–16, 10–17, 10–22 Metrics category, 3–22
programming languages Pascal category, 3–47
selecting for project, 3–10 PL/M category, 3–50
setting in Source Editor, 6–4 Reports category, 3–24
variants of, support for, 1–4 saving configuration, 3–9
project, 2–3 Scheduled Activities category, 3–19
adding source files on command line, 13–3 Visual Studio category, 3–26

Index–18 Understand 2.0 User Guide and Reference Manual

 Index

Project Graphical Views option, Project wild card, 5–6

menu, 2–18, 10–7 quiet option, und command, 13–8
Project Interactive Reports option, Project quote (") prefixing octal constants or string
menu, 2–18, 10–7 literals, 3–41
Project menu, 14–3 quotes ("") surrounding normal
Analyze All Files option, 3–20, 3–67 includes, 3–35
Analyze Changed Files option, 3–67
Configure option, 3–8 R
Project Assistant option, 4–4 read-only access, 3–18
Project Browser option, 4–14 Recent files most recently use list field, User
Project Graphical Views option, 2–18, 10–7 Interface Lists options, 3–55
Project Interactive Reports option, 2–18, Recent projects most recently use list field,
10–7 User Interface Lists options, 3–56
Project Overview Graphs option, 9–2 Recent Projects option, File menu, 2–6
Project Reports option, 10–2 recently used lists, options for, 3–55
Rescan Watched Project Directories Record Macro option, Tools menu, 6–11
option, 3–15, 3–20 rectangles, in graphical views, 9–18
Project Metrics Browser, 11–2 rectangles, rounded, in graphical views, 9–18
Project Metrics report, 10–24 red project file icon, 6–3
Project Metrics Summary option, Metrics red text, 3–65
menu, 11–2, 11–3 reference files, C#, 3–39
Project Overview Graphs option, Project References category, C#, 3–39
menu, 9–2 References, in Info Browser, 4–12
Project Reports option, Project menu, 10–2 regular expressions
Prompt before closing the current project book about, 5–7
field, User Interface Alerts options, 3–56 in filters for Entity Locator, 5–6
Prompt for missing includes field, C++ in Find dialog, 6–8
Includes, 3–35 relationship, 2–3
Prompt on parse errors field relative portability mode, 3–16
Ada, 3–30 -removeDir option, und command, 13–9
FORTRAN, 3–42 -removeFiles option, und command, 13–9
$Prompt variables, 12–4, 12–5, 12–6 Rename Architecture menu option, 7–5
prompt when files modified externally, 3–62 Rename Declaration View, 9–14
Protected Members menu, graphical rename declarations
views, 9–26 displayed in graphical views, 9–26
Public Members menu, graphical views, 9–26 reports about, 10–17
pushpin icons, 2–2 Renames menu, graphical views, 9–26
Renames report, 10–17
Q Replace in Files area, 5–11
quality reports, 10–18 Replace in Files option, Search menu, 5–11
question mark (?) Replacement Text category
in regular expressions, 5–7 C++ Includes, 3–36

Understand 2.0 User Guide and Reference Manual Index–19

 FORTRAN Includes, 3–42 Output subcategory, 3–24, 10–2
Replay Macro option, Tools menu, 6–11 Selected subcategory, 3–25, 10–3
-report option, und command, 13–9 Requirements predefined architecture, 7–10
-report_Filename option, und -rescan option, und command, 13–9
command, 13–9 Rescan Watched Project Directories
-report_htmldir option, und command, 13–9 option, 3–15
-report_htmlstyle option, und Rescan Watched Project Directories option,
command, 13–9 Project menu, 3–15, 3–20
-report_htmltitle option, und command, 13–9 Reuse window when requesting a similar
-report_sel option, und command, 13–9 type of graph from within window field,
-report_textdir option, und command, 13–9 General options, 3–53
-report_textfile option, und command, 13–9 Reverse-Dependency Graph, 7–6, 9–10
-report_textstyle option, und command, 13–9 RFC (Count of All Methods) metric, 10–25
-report_time option, und command, 13–9 Right-click Menu
reports, 2–17, 10–2 external tools available in, 12–4, 12–10
anti-virus software, turning off while Find in Files option, 5–8
generating reports, 10–4 right-clicking, 2–2, 4–2
canceling generation of, 10–4 + or - sign in Info Browser tree, 4–9
categories of, 10–6 on Analyze icon, 3–67
on changed entities, 8–19 anywhere in Understand, 2–7
configuring, 10–2 in Architecture Browser, 7–4
cross-reference reports, 10–8 in background of graphical views, 9–19
customizing with Perl or C, 2–18, 10–7, bold heading in Info Browser, 4–10
11–2 creating windows by, 2–7
entity name format in, 3–25 on entities in graphical views, 9–6
filenames for, 10–5 on entities to display source, 4–11
generating, 10–2, 10–4 on entities in Entity Locator, 2–10
generation time of, 3–25, 10–4 on entities in Entity Locator entities, 5–5
HTML output, 3–24, 10–4 on entities in Info Browser, 2–8
HTML output, entity index for, 10–5 on entities in Source Editor, 2–7, 2–13
HTML reports for Change Results in Entity Filter, 2–8
window, 8–27 in Entity Locator, 5–3
list of, choosing from, 3–25, 10–3 on Entity Locator column headers, 5–4,
metrics reports, 10–23, 11–2 5–6
quality reports, 10–18 in Info Browser, 4–13
structure reports, 10–14 on Selector window, 5–15
text output, 3–25, 10–4 reusing windows by, 2–7, 4–2
viewing, 10–5 on selected text, 6–4, 6–11
See also specific reports in Source Editor, 6–5
Reports category, Project Configuration on Source Editor tabs, 6–13
dialog, 3–24 See also Ctrl+right-click
Options subcategory, 3–25 RO (read-only) indicator, in Source

Index–20 Understand 2.0 User Guide and Reference Manual

 Index

Editor, 6–4 Sidebar, 6–9

Root filters, Entity Filter, 4–7 Scope List, Source Editor, 6–3
-rootAdd option, und command, 13–9 See also Structure Browser, Source
-rootList option, und command, 13–10 Editor, 6–9
-rootMode option, und command, 13–10 toolbar for, 5–15
-rootRemove option, und command, 13–10 Scratch from Current Database
-rootReset option, und command, 13–10 snapshot, 8–3, 8–4
Routines menu, graphical views, 9–26 scripts, Perl, 2–4
routines. See functions; procedures Search for include files among project files
row colors, alternating, 3–54 field, C++ Includes, 3–35
Run a Command option, Tools menu, 12–15 Search menu, 6–7, 14–3
Run at License Level option, Help menu, 1–3 Entity Locator option, 2–10, 5–3
-runAsLicenseLevel option, understand Favorites option, 2–11
command, 13–12 Find in Files option, 2–11, 5–8
RW (read-write) indicator, in Source Find option, 6–8
Editor, 6–4 Incremental Find option, 6–7
Replace in Files option, 5–11
S Search Paths Category, Pascal, 3–49
Save all modified editor windows when searching
application loses focus field, General files, 5–8, 6–7
options, 3–52 graphical views, 9–6
Save All option, File menu, 6–6 Selected subcategory, Reports, 3–25, 10–3
Save comments associated with entities field selecting text, 8–23
Ada, 3–30 Selector option, Window menu, 5–15
C++, 3–33 sharp sign (#) comment in command line
Java, 3–43 file, 13–5
Save duplicate references field, C++, 3–33 shortcut commands, 3–57
Save macro expansion text field Show Page Guide field, Editor options, 3–63
C++, 3–34 Show standard library files field, Analyze
Save on command field, User Interface Alerts options, 3–59
options, 3–56 Show tabs field, User Interface options, 3–55
Save on parse field, User Interface Alerts Show the Getting Started dialog on startup
options, 3–56 field, General options, 3–52
Save option, File menu, 6–6 Show the Splash-Screen on startup field,
saving edits automatically, 3–52 General options, 3–52
Scale menu, graphical views, 9–27 Simple Invocation Tree report, 10–16
Scheduled Activities category, Project Simple With Tree report, 10–17
Configuration dialog, 3–19 SlickEdit editor, 12–3
Scheduled Activities option, Tools sliding frames, 2–2
menu, 3–19 Snapshot Manager, 8–2, 8–10
SciTools forum, 10–7 copying information from snapshots, 8–13
Scope Information, Contextual Information creating snapshots, 8–3

Understand 2.0 User Guide and Reference Manual Index–21

 deleting snapshots, 8–12 case, changing in, 6–11
editing snapshots, 8–11 closing files, 6–6
enabling and disabling snapshots, 8–12 colors in, customizing, 3–65, 6–2
protecting and unprotecting colors in, default, 3–65
snapshots, 8–13 commenting and uncommenting
purging snapshots, 8–13 code, 6–10
-snapshot option, und command, 13–10 configuring, 3–61
Snapshot windows, 2–15 Contextual Information Sidebar (CIS)
-snapshotComment option, und in, 6–9
command, 13–10 copying to clipboard from, 6–4
snapshots, 2–4, 2–15, 8–2 creating files, 6–11
compared to TrackBack tool, 8–2 displaying by right-clicking on
comparing, 8–14 entities, 4–11
comparing entities between, 8–29 displaying from Find Results
comparing, results from, 8–17 window, 2–11, 5–10
copying information from, 8–13 external editor replacing, 12–2
creating, 8–3 folding (hiding blocks in) code, 6–10
creating after analyzing project, 3–68 hiding inactive lines in, 6–10
creating automatically, 3–20, 8–3 history of locations visited in, moving
creating from other locations, 8–6 through, 6–8
deleting, 8–12 jumping to specific line number, 6–4
editing, 8–11 keystrokes in, list of, 6–11
enabling and disabling, 8–12 language, setting, 6–4
managing. See Snapshot Manager line numbers displayed in, 6–2
memory used by, 8–2, 8–12 list of specific structures in, 6–3, 6–9
metric graphs about, 11–9 location of, 2–4
of older generations of source code, 8–2 macros of editing changes, recording and
protecting and unprotecting, 8–13 replaying, 6–11
purging, 8–13 moving between windows of, 2–13
types of, 8–3 opening files, 6–11
"Software Engineering with Ada" printing from, 3–64, 6–14
(Booch), 9–14 read-write (RW) and read-only (RO)
Sort menu, graphical views, 9–27 indicators, 6–4
sorting entities, 4–5 right-clicking in, 2–7, 2–13, 6–5
Sound beep on parse completion field, right-clicking tabs in, 6–13
Analyze options, 3–59 saving files, 6–6
Source Editor, 2–13, 6–2 Scope List in, 6–3
auto-complete options, 3–64 searching and replacing text in source
bookmarks, creating, 6–12 files, 6–8
bookmarks, navigating, 6–12 searching in source files, 6–7
bracket matching in, 6–10 status bar in, 6–3
Browse Mode in, 6–4 status icon in, 6–3

Index–22 Understand 2.0 User Guide and Reference Manual

 Index

tabs in, controlling behavior of, 6–13 read-only access for, 3–18
toolbar for, 5–15 removing from project, 4–15
TrackBack revisions count in, 8–36 saving, 6–6
source files searching, 2–11, 4–15, 5–8, 6–7
adding to project, 3–6, 3–11, 4–15 Sources tab, Project Configuration
adding to project on command line, 13–3 dialog, 3–11
analyzing using projects. See project spaces, converting tabs to, 3–62
closing, 6–6 Spacing menu, graphical views, 9–27
creating, 6–11 special member functions, C++, 3–33
declaration structure for, 9–14, 9–16 splash screen, displaying at startup, 3–52
deleting from project, 3–14 split workspace, 5–14
directories for, adding to project, 3–12 toolbar for, 5–15
directories for, deleting from project, 3–14 Sql menu, graphical views, 9–27
displaying by double-clicking entity, 4–11 SQL, embedded, in Pascal, 3–47
displaying by right-clicking on square brackets. See brackets
entities, 4–11 [Link] file, 3–44
displaying from Find Results [Link] file, 3–44
window, 2–11, 5–10 Staff predefined architecture, 7–10
editing. See Source Editor Standard field, Ada, 3–29
encoding for, 3–18, 3–61 standard libraries
excluding from source list, 3–13 Ada, directory for, 3–29
external editor for, 12–2 displaying in parse log, 3–59
imported classes in, 9–16 Pascal, paths for, 3–49
imported, report about, 10–17 Standard Library Paths category,
include files specified as, C++, 3–34 Pascal, 3–49
include files specified as, FORTRAN, 3–42 Start menu, Understand commands in, 2–5
include files specified as, PL/M, 3–50 startup
include hierarchy for, 9–10, 9–12 Getting Started dialog displayed on, 3–52
line endings for, 3–61 Splash-Screen displayed on, 3–52
list of, generating from command static functions, displayed in graphical
line, 13–4 views, 9–27
listing in Filter Area, 2–9 Static menu, graphical views, 9–27
metrics about, 10–26 status bar, Source Editor, 6–3
moving between windows of, 2–13 status icon, in Source Editor, 6–3
opening, 6–11 status line, 2–4
opening from graphical view, 9–6 %STI_INIDIR% environment variable, 2–6
overriding settings for, 3–15 strict complexity, count and/or operators in,
as parallelograms, in graphical Ada, 3–29
views, 9–18 Strict metric, 10–27
portability of, 3–16 Structure Browser, Contextual Information
printing, 6–14, 9–32 Sidebar, 6–9
printing, configuration for, 3–64 structure reports, 10–14

Understand 2.0 User Guide and Reference Manual Index–23

structure views, 2–16, 9–5, 9–14 Title Formats field, User Interface
See also declaration views; graphical options, 3–55
views title page, 3–25
Styles category, Editor options, 3–65 tool commands, importing and
subprograms, listing in Filter Area, 2–9 exporting, 12–14
subtraction sign (-) collapsing tree in Info Tool Configurations dialog
Browser, 4–9 Popup Menu category, 12–10
successive filters, for architectures, 7–16 Toolbar category, 12–13
Sum Complexity metrics graph, 11–9 toolbar
support contact information, 1–4 external tools available from, 12–13
SVG format, saving graphical views as, 9–30 hiding and displaying icons, 5–15
switches, command line location of, 2–4
und command, 13–5 visibility of icons in, controlling, 12–14
understand command, 13–11 Toolbar category, Tool Configurations
symbolic links, adding files with, 3–13 dialog, 12–13
synchronizing Info Browser, 4–11 Tools menu, 14–5
"System Design in Ada" (Buhr), 9–14 Configure User Tools option, 12–3, 12–14
system include files, C++, 3–35 External Editor Settings option, 12–2
Master Scheduler List option, 3–21
T Options option, 3–51
Table View of graphs, 9–3 Record Macro option, 6–11
Table View, for metrics graphs, 11–11 Replay Macro option, 6–11
tabs for windows, displaying, 3–55 Run a Command option, 12–15
tabs, converting to spaces, 3–62 Scheduled Activities option, 3–19
Task View, 9–14 TrackBack History Explorer option, 8–36
tasks User Tools option, 12–4, 12–12
declaration structure for, 9–14 tools, external. See external tools
With relationships for, 9–14 TrackBack category, Understand Options
technical support contact information, 1–4 dialog, 3–58
text TrackBack History Explorer option, Tools
comparing, 8–35 menu, 8–36
copying to clipboard, 6–4 TrackBack tool, 8–2, 8–9, 8–36
generating reports as, 2–17, 3–25, 10–2, toolbar for, 5–15
10–4 Treat system includes as user includes field
selecting, 6–4 C++ Includes, 3–35
size of, in graphical views, 9–27 Tree row indentation field, User Interface
viewing reports as, 10–5 options, 3–54
Text Comparison window, 8–35 Tree view, Changed Entities area, 8–18, 8–20
Text menu, graphical views, 9–28 Truncate column field
TextPad editor, 12–2 FORTRAN, 3–41
title areas, filenames in, 3–55 JOVIAL, 3–45
title bar, 2–2 Truncate Long text option, 9–28

Index–24 Understand 2.0 User Guide and Reference Manual

 Index

Truncate Medium text option, 9–28 Understand 1.4, converting to 2.0, 3–69
Truncate Short text option, 9–28 understand command, 13–11
truncation at column Understand Options dialog, 3–51
FORTRAN, 3–41 Analyze category, 3–59
JOVIAL, 3–45 Command Window category, 3–59
Turbo Pascal, 3–47 Configure category, 3–59
Type Cross-Reference report, 10–11 Editor category, 3–61
Type Derived From View, 9–10 General category, 3–52
Type Tree View, 9–10 Key Bindings category, 3–57, 6–11
types Portability category, 3–60
displayed in graphical views, 9–28 TrackBack category, 3–58
as hexagons, in graphical views, 9–18 User Interface category, 3–54
information about, 9–14, 9–16 undocking windows, 2–2
listing in Filter Area, 2–9 Unicode file handling, in Entity Comparison
reports about, 10–11, 10–21 area, 8–25
types derived from, 9–10 Uninitialized Items report, 10–20
Types menu, graphical views, 9–28 UNIX
Typetext menu, graphical views, 9–28 line termination style, for reports, 10–4
line termination style, for saving source
U files, 3–62
.udb file extension, 2–3, 3–2 symbolic links used when adding
und command, 13–1, 13–2 files, 3–13
adding files to project, 13–3 unknown entities, displaying in graphical
analyzing a project, 13–4 views, 9–28
creating new project, 13–3 Unknown menu, graphical views, 9–28
options for, list of, 13–5 unresolved entities
options in latest version, listing, 13–2 displaying in graphical views, 9–29
UndDiff program, 8–32 Unresolved menu, graphical views, 9–29
undefined macros, C++, 3–38 unresolved variables, listed in Entity
Undefines category, C++ Macros, 3–38 Locator, 2–10
Understand Unused Object report, 10–21
compared to compiler, 3–2 Unused Program Unit report, 10–22
contact information, 1–4 Unused Type report, 10–21
editions of, 1–3 Unused Variables and Parameters
features of, 1–2 report, 10–21
licensing of, 1–3 Update Information Browser field, Browse
multiple users for, 2–6 Mode Editor options, 3–66
online help for, 1–5, 2–6 uperl command, 2–4
programming languages supported, 1–4 Use alternating row colors field, User
starting, 2–5 Interface options, 3–54
starting from command line, 13–11 Use case-insensitive lookup for includes field
windows in, 2–2, 2–4 C++ Includes, 3–35

Understand 2.0 User Guide and Reference Manual Index–25

Use default Framework directory field, vertical bar (|) in regular expressions, 5–7
C#, 3–39 Vertical Non-Crossing layout option, 9–24
Use default working directory field, General vi editor, 12–3
options, 3–53 View SciTools Blog option, Help menu, 1–5
Use Framework directory field, C#, 3–39 views. See declaration views; graphical
Use include cache field, C++, 3–34 views; hierarchical views
Use preprocessor field, FORTRAN, 3–41 Visio files, saving graphical views as, 9–30
Use sources in standard directory, C#, 3–39 -visit option, understand command, 13–12
Use the New Project Wizard when creating Visit Source field, Browse Mode Editor
new projects field, Configure options, 3–59 options, 3–66
Used By View, 9–11 Visual C++, as editor, 12–2
Usedby Menu, graphical views, 9–29 Visual Studio as external editor, 12–3
User Interface category, Understand Options Visual Studio category, Project Configuration
dialog, 3–54 dialog, 3–26
user interface, parts of, 2–4 Visual Studio files, synchronizing with
User Tools option, Tools menu, 12–4, 12–12 Understand project, 3–5, 3–26
users, multiple, initialization files for, 2–6 -vsFile option, und command, 13–10
Uses Menu, graphical views, 9–29 -vsFileConf option, und command, 13–10
Uses View, 9–11 -vsFileDel option, und command, 13–10

V W
variables warnings, displaying from Parse Log
displayed in graphical views, 9–29 window, 3–68
instance, 10–25 watched directories
listed in Entity Locator, 2–10 scanning, 3–15, 3–20
metrics about, 10–25 setting, 3–13, 3–14
reports about, 10–10, 10–20, 10–21 websites
as rounded rectangles, in graphical Change Log, 10–19
views, 9–18 external editor information, 12–3
uninitialized, report about, 10–20 metrics, list of, 10–18, 10–23, 11–3
unresolved, 2–10 O’Reilly and Associates, 5–7
See also objects Perl interface, 11–2
Variables menu, graphical views, 9–29 SciTools forum, 10–7
.vcp file extension, 3–26 white file icon, 6–3
.vcw file extension, 3–26 whitespace
Version field in Entity Comparison area, 8–25
Ada, 3–28 indicators for, 3–63
FORTRAN, 3–40 Whitespace field, Editor options, 3–63
Java, 3–43 wild cards, in filters for Entity Locator, 5–6
JOVIAL, 3–45 %WINDIR% environment variable, 2–6
Pascal, 3–47 Window menu, 5–14, 14–6
-version option, und command, 13–10 Bookmarks option, 5–15

Index–26 Understand 2.0 User Guide and Reference Manual

 Index

Close All Document Windows option, 6–6 X

Close option, 6–6
XML Export, 7–5, 7–15
Entity Graphs option, 9–6
XML, sharing architectures using, 7–15
Navigator option, 5–14
Selector option, 5–15
windows, 2–2, 2–4
Y
animated opening and closing of, 3–54 yellow background for text, 3–66
closing, 2–2 yellow project file icon, 6–3
creating with Ctrl+right-click, 2–7, 4–2
docking and undocking, 2–2 Z
docking layout for, 3–55 zooming graphical views, 9–7
filenames in title area of, 3–55
frames in, sliding, 2–2
graphs in, reusing, 3–53
list of, 4–3
list of open windows, 5–14, 5–15
organizing, 5–14
reusing for graphical views, 9–9
reusing with right-click, 2–7, 4–2
tabs for, displaying, 3–55
Windows CE project, 3–26
Windows CE workspace, 3–26
Windows folder, 2–6
Windows line termination style
for reports, 10–4
for saving source files, 3–62
With Bys menu, graphical views, 9–29
With Tree report, 10–16
With View, 9–11
WithBy View, 9–11
Withs menu, graphical views, 9–29
Withs Not Needed report, 10–22
WMC (Count of Methods) metric, 10–25
workbench file, 3–26
working directory, default, 3–53
workspace file, 3–26
Wrap Long text option, 9–28
Wrap Medium text option, 9–28
Wrap Mode field, Advanced Editor
options, 3–64
Wrap Short text option, 9–28

Understand 2.0 User Guide and Reference Manual Index–27

Index–28 Understand 2.0 User Guide and Reference Manual