Working with Architect models and custom diagrams

From Insight-9.2

Contents

This how-to provides detailed information on working with models and custom diagrams in Klocwork Architect. See Getting started with Klocwork Architect for basic information on getting started with Architect.

Viewing relationships between entities

Relationships between entities are displayed as arrows in the Graphic view. Architect also displays relationships to the environment--that is, relationships to entities at other levels of the hierarchy, and entities that exist outside the model.

You can turn arrows on or off or choose what kinds of relationships will display as arrows.

Architect rels displayed w CD.jpg

The number beside an arrow tells how many relationships of the selected types are being displayed.

Tip: If the relationship arrows overlap in the Graphic view, the numbers will be difficult to read. You may need to move or resize blocks so that you can view the numbers clearly. You can also try the hierarchical layout.

You can also view detailed information about specific relationships in the Relationship Viewer. For a complete list of Architect relationship types, see Supported relationship types.

Managing how you view relationships

To set up what relationships (if any) will display as arrows in the Graphic View, you use the Relationship Profile Editor. You save your choices in a profile you can reuse when you look at another custom diagram or model. You may find it useful to create various profiles appropriate to specific tasks that you do often. To apply your changes, you exit from the Relationship Profile Editor and select the profile you want to use from the Relationship Profiles list on the main toolbar.

The first time you open a Graphic view, Klocwork displays all relationships. Thereafter, Klocwork applies the profile you used last.

When you move to different levels of the hierarchy within a Graphic view, the profile you applied still determines the relationships you see.

To set up a relationship profile:

  1. Open a Graphic view of the custom diagram model you want to edit. To open a Graphic view, right-click the custom diagram or model name in the Project Tree view and click Open, or double-click any entity in the Project Tree view.
  2. Navigate to the level of the hierarchy where you want to view relationships.
  3. Click View > Edit Relationships Profiles....
    The Relationship Profile Editor opens.
    Note: The list of relationship types you see may differ depending on the programming language and the relationship types present in your source code.
  4. Build a relationship profile. You can use an existing profile as a starting point and click Save as to save the profile under a new name or you can click New to start from whatever profile is currently in use. There are four default relationship profiles included with Klocwork:
    • All Relationships
    • Call Graphs
    • Inheritance Structure
    • No Relationship
    You cannot change or delete the default relationship profiles.
    (Optional) For descriptions of the relationship types, see Supported relationship types.
    (Optional) For an expanded list of relationship types, click Advanced.
  5. If you have created or modified a profile, click Save or Save As and, if necessary, assign a name to your new profile.
    Note: You use the Relationship Profiles list within the Relationship Profile Editor to help you build a relationship profile, but to apply your changes to the Graphic view, you must use the Relationship Profiles list on the main toolbar.

To apply a profile of relationships to a Graphic View:

On the main toolbar bar, in the relationship profiles list, select a relationship profile.
In the Graphic view the arrows now indicate the relationship profile you selected.

Note 1: If you have other Graphic views of the same model open, when you apply a relationship profile, they do not change to the new relationship profile automatically. However, any new Graphic views you open will display the most recently applied relationship profile.

Note 2: Architect views update faster, when you select No relationship.

Enabling and disabling relationships to the environment

By default, when you display relationships in the Graphic view, Architect displays relationships to the environment--that is, relationships to entities at levels of the hierarchy outside the Graphic view. If you want to focus only on internal behavior, you can turn off the display of relationships to the environment.

To disable the display of environment relationships, click View > Show Environment Relationships. The menu item is now de-selected, and relationships to the environment are not shown.

To re-enable environment relationships, click View > Show Environment Relationships again. The menu item is now selected, and relationships to the environment are shown.

Turning on or off the display of relationships to the environment enables or disables the relationships to the environment of the current Graphic view only. In other words, you are turning the arrows on to the borders of the Graphic view, not to the environment of the whole model.

Undefined entities of system and third-party include directories are in "<library>" files

The system and third-party include directories, with all the appropriate header files inside them, appear in the System model in the same way as any other include directories. System and third-party headers only provide declarations, and the definition of most entities (functions, variables, methods, and so on) is hidden inside the binary libraries that are not part of Klocwork analysis. Consequently, these undefined entities go into a special file called "<library>". This <library> file is created for each include directory that declares this kind of undefined entities.

Example:

The function 'printf' is declared in /usr/include/stdio.h system header file. The System model will look like this:

System Model
+- DIRECTORY usr
+- DIRECTORY include
+- FILE stdio.h
| +- FUNCTION-DECLARATION int printf(char *, ...)
+- FILE <library>
+- FUNCTION int printf(char *, ...)

These two 'printf' entities are connected to each other with a DECLARED-BY relationship.

Unknown entities

An unknown entity is an entity (a function, variable, or macro, for example) that is neither defined nor declared, although it is used in the project's codebase. Klocwork does not recognize unknown entities as part of a project and does not include them in the System model. All relationships to an unknown entity point to the model's environment.

Displaying relationship details

You can view detailed information about specific relationships in the Relationship Viewer.

To display relationship details:

  1. While viewing relationships in the Graphic view, right-click on the line between two entities.
    Architect - rel viewer edge popup.jpg
    The Edge pop-up menu appears. Two menu items are displayed, allowing you to select the relationship direction. If the relationship you clicked on is uni-directional, one of the menu items will be grayed out.
  2. Select a menu item.
  3. The Relationship Viewer opens in the List pane.

Architect Relationship Viewer Displaying rel details.jpg

Tips:

  • If a Relationship Viewer tab is already open and is unpinned, the Relationship Viewer displays the mode (that is, Relationships or Interfaces) last used in the current Architect session. Otherwise, the Relationship Viewer opens in the default Relationships mode.
  • You can sort information in List views by clicking any of the column headers. The Sort arrow indicates which column has been used for sorting, as well as the direction of the sorting.
  • You will not be able to sort the results in the Relationship Viewer if you’re displaying more than 3000 records. However, you can export the list and view it in an external viewer. See Saving relationship and interface information to file.
  • If a relationship points to an entity that exists outside the System model, the last column in the Relationship Viewer displays @__UNDEFINED__@.
  • To see more information on the individual relationships listed, right-click on items in the Identifier, in File, and uses Identifier columns to open a pop-up menu.

Displaying interface details

You can view detailed information about interfaces between components in the Relationship Viewer.

An interface is a symbol or set of symbols that enables a connection between two entities in a dependency relationship. An entity that provides symbols used by another entity can be said to have a server interface. The entity that receives and uses symbols from another entity can be said to have a client interface. The interfaces view provided by Architect enables you to view the complete server or client interface of a certain entity, taking into account all dependency relationships with other entities.

For example, if there are two calls to Entity A from Entity B, and 3 calls to Entity B from Entity A, there is a total of five relationships between the two entities. But there are only two interfaces (A and B are the interface points). The number of interfaces is always less than or equal to the number of relationships.

This list of interfaces is useful for doing architectural restructuring. It is also useful when the list of usage relationships is very large but consists only of a few symbols used many times.

To display interface details:

  1. While viewing relationships in the Graphic view, right-click the line between two entities.
  2. The Edge pop-up menu appears. Two menu items are displayed, allowing you to select the relationship direction. If the relationship you clicked on is uni-directional, one of the menu items will be grayed out.
  3. Select a menu item.
  4. The Relationship Viewer opens in the List pane.
    Note: If a Relationship Viewer tab is already open and is unpinned, Relationship Viewer displays the mode (that is, Relationships or Interfaces) last used in the current Architect session. Otherwise, the Relationship Viewer opens in the default Relationships mode.
  5. Click the Interfaces icon Architect view interfaces icon.gif in the List view toolbar.
    The relationship information displayed is replaced with information about the interfaces between the connected entities.
    Architect relationship viewer interfaces.jpg
    The Density column displays the number of relationships to the given entity (identifier).
    Tip: You can sort information in List views by clicking any of the column headers. The Sort arrow indicates which column has been used for sorting, as well as the direction of the sorting.
    To see more information on the individual interfaces listed, right-click on items in the uses Identifier or in File columns to open a pop-up menu.

Relationships to the environment vs. relationships to the parent entity

When you view relationships between an entity and the environment, the number of relationships may not match the number of relationships to the environment you see when you enter the entity.

For example, consider the following Graphic view of the contents of file binBuffer.h:

Architect env relationship numbers 1.jpg

You will note that BinBufferSend, a class, has three relationships to the environment. When we right-click the relationship arrow and choose relationships from BinBufferSend to the environment, we see the following details in the Relationship Viewer:

Architect env rels details 1.jpg

All three of the relationships to the environment point to entities in the file binBuffer.C.

If we enter the class BinBufferSend by double-clicking it, we see the following sub-entities:

Architect env relationship numbers 2.jpg

If we count the numbers of relationships to the environment now (looking at all of the arrows that point to the boundary of the diagram), we see that there are not three, but 12.

When we view relationship details for the relationships from operator<< to the environment, for example, we see the following details in the Relationship Viewer:

Architect env relationship details 2.jpg

In this case, we see that one of the relationships points to the file binBuffer.C, but two of the relationships point to binBuffer.h, which is the parent entity of BinBufferSend.

If we were to view relationship details for each sub-entity that has relationships to the environment, we would see that there are still three relationships to the file binBuffer.C; the remaining nine relationships point to the parent entity, binBuffer.h. When you enter an entity, relationships to the parent entity are treated the same as relationships to the environment.

Tip: At the file level and above, you can expand an entity (select expand in the entity right-click menu) to differentiate between relationships to the parent entity and relationships to the environment.

Finding cyclical dependencies in the code

A cyclical dependency, or cluster, is a group of software entities that has circular dependencies between all of the entities in the group. By viewing clusters, you may be able to determine how to reduce cyclical dependencies. Benefits of reducing cyclical dependencies include easier maintainability and testing, and separation of components for reuse.

Note that the number and the contents of clusters shown in Architect depend on two things:

  • the level of the hierarchy you are viewing
  • the types of relationships displayed

To view clusters:

  1. Open a Graphic view of a model. To do this, right-click the model name in the Project Tree view and click Open.
  2. By default, relationships are displayed. If they are not, see Managing how you view relationships.
  3. Click Tools > Find Clusters....
    If clusters exist at the level of the current diagram, the Find Clusters dialog appears, showing a list of clusters of files in the current diagram, with the largest cluster at the top of the list:
    Architect - find clusters dialog.jpg
    Clusters appear in the list only if:
    If no clusters exist at the level of the current diagram, a "No clusters found" message is displayed.
  4. Double-click on a cluster in the list, or select it and click Highlight.
    The files in the cluster are highlighted, and the relationships between them are highlighted in red.
  5. Move or modify the files in the cluster view as desired.

Guidelines for analyzing and breaking clusters

This section provides some hints on how to break a cluster.

Determine when the clusters occur

Clusters may occur at compile time or run time, or they may have been created during the design phase. You may want to focus only on those clusters that were created in the design phase, or occur at compile time. You may not be concerned about clusters that occur at run time.

To simplify cluster analysis, you can isolate only the relationship types that occur during the phase you’re interested in. While viewing a cluster, use the Relationship Profile Editor to set up a profile that displays only certain types of relationships. For details on the available relationship types, see Supported relationship types. For details on how to set up relationship profiles, see Managing how you view relationships.

For example, to view compile-time clusters, display only "Includes" and "File uses macro" relationship types.

To view run-time clusters, display only "Calls", "Reads", and "Writes" relationship types.

To view clusters created during the design phase, display all relationship types except those listed above.

Break the bi-directional relationships before the uni-directional relationships

Since the bi-directional relationships between files are most problematic, examining and breaking them first helps speed cluster breaking.

Break the shortest paths first

A cluster is made up of many paths from one node to other nodes and back to the original node. Examining and breaking the shortest paths in the cluster first is recommended. Once the shorter paths are broken, the longer paths may disappear as well.

Try various refactoring methods

The possible refactorings for breaking a cluster between entities A and B are:

  • Move A (and everything A uses) into B
  • Move B (and everything B uses) into A
  • Move A (and everything A uses) into a new file
  • Move B (and everything B uses) into a new file
  • Move A and B (and everything A and B use) into a new file

Experiment with these refactoring methods for each bi-directional relationship to see which helps to break the cluster.

Using the Relationship Viewer list to move entities

You can drag entities from the Relationship Viewer list to the Project Tree view or Graphic view. This is an easy way to move entities from one location in the model hierarchy to another.

Notes

  • You cannot drag files in Java projects.
  • You can drag entities between models if the entity you are attempting to drag exists in both models. For example, if you displayed relationship details for Model A, you can drag an entity from the Relationship Viewer list into a new position in Model B, if the entity also exists in Model B. (This restriction does not bind custom diagrams. In custom diagrams you can arrange entities without regard for their location in the source software.)
  • In models, entities that are below the file level (class or interface level for Java) can only be dragged into file-level (class or interface level) entities. File-level (class or interface level for Java) entities can only be dragged into directories and other architecture blocks above the file (class or interface level) level. (These restrictions do not bind custom diagrams. In custom diagrams you can arrange entities without regard for their source hierarchy.)
  • When viewing relationship details, you can drag the identifier listed in the Identifier column and the uses Identifier column. You can also drag the file entity listed in both in File columns.
  • When viewing interface details, you can drag the identifier listed in the Uses Identifier column or the file entity listed in the in File column.
  • You can also drag entities from the Search list. See Using the Search list to move entities.

To move entities from the Relationship Viewer list into the Project Tree view or Graphic view:

  1. Display relationship details as described in Displaying relationship details. Or, display interface details as described in Displaying interface details.
    Relationship (or interface) details are displayed in the Relationship Viewer tab.
  2. In the Graphic view or Project Tree view, navigate to the level of the hierarchy where you want to move an entity displayed in the Relationship Viewer list.
  3. In the Relationship Viewer list, click on the entity you want to move and drag it onto the Graphic view or Project Tree view.
    The entity appears in its new location in the model.

Creating new models

By default, Klocwork Architect creates the System model, which shows you the existing physical design of your system along with the relationships and interfaces between entities in the system. Exploring the System model can help you understand how your software system is organized.

You can also create your own models, which allow you to experiment with the design of your system. Architect automatically recalculates the relationships between entities, allowing you to immediately see the impact of your changes.

Models are automatically propagated when the project on which they are based is reanalyzed. For more information, see Updating Architect user models to reflect a new project build.

The modeling capability of Architect can help you solve many problems related to software development and maintenance, such as:

  • assessing and improving the quality of your software system design
  • isolating reusable components
  • porting to a new platform

You can create a model in two ways:

  • base the new model on an existing model
  • import an XML file

Creating a model based on an existing model

You can create models based on System model, a model you own, or a model shared by another user. To create your own model based on an existing model:

  1. Open the build on which you want to base the model.
  2. Do one of the following:
    • Click File > New model.
    • In the Project Tree view, right-click the model you want to base the new model on, and select New model, or click the New Model button in the main Toolbar.
    • Open a Graphic view of the model you want to base the new model on, and click File > Save as.
    The Set Model Name dialog opens.
  3. Enter a name for your new model. The model name can have a maximum of 30 characters. The name must not contain spaces. Only alphanumeric and underscore characters are permitted.
    Note 1: You cannot use a name that is already in use for this project build (by yourself or any other Architect user working on this build).
    Note 2: The name is stored case-insensitive in the Klocwork database. Therefore, you cannot name your model "MODEL_1", for example, if a model already exists with the name "model_1".
  4. Click OK.
    The new model appears in the list of models in the Tree view. The list of models is arranged in alphabetical order.
    The model also appears in the Graphic view, ready for editing.
    Note: Subsequent changes to the same model can be captured using the Save command on the File menu.

Creating a subsystem model

Architect users sometimes want to work with only a subsystem within a larger software system. You can create a model that represents this subsystem.

Before you can create a model of a subsystem within a larger software system, you must have a project based on the full software system. You then use Architect to establish the scope of the subsystem.

To create a subsystem model:

  1. In Architect, create a new model based on the System model. See Managing how you view relationships.
  2. Use this model to identify the set of source files that you want to include in your subsystem.
  3. Group this set of files into an architectural block.
  4. Examine relationships from the architecture block to other portions of the system under study. This exposes all direct dependencies from the files of interest to other segments of the system.
  5. Examine relationships to the architecture block from other portions of the system. This exposes all direct dependencies of the system to the files in the subsystem.
  6. Delete entities unrelated to the subsystem. This will help reduce the size of the subsystem model.
  7. Save the subsystem model.

Creating and working with custom diagrams

When you create a new custom diagram, you always begin with the File > New Custom Diagram command, then add at least one entity and choose a relationship profile. After you have created the custom diagram, you have the choice of continuing to work with it in the Project Tree view and the Graphic view or of using the Edit > Build Custom Diagram command. The Edit > Build Custom Diagram command is a sophisticated tool that lets you manage what entities are included in the custom diagram and work through usage levels quickly and efficiently.

Creating a new custom diagram

To create a new custom diagram:

  1. Click File > New Custom Diagram.
    The Set Custom Diagram Name dialog box appears.
  2. Enter a name for your new custom diagram.
    You can use alphanumeric characters and the underscore character to a total of 64 characters.
  3. Click OK.
    A new Graphic view opens, with a tab showing the name of the new custom diagram. In the Project Tree view, the new custom diagram entity appears.
  4. Determine what entities you want to work with in your custom diagram and drag at least one entity from the System Model in the Project Tree view or from the List view into the Graphic View of your custom diagram.
  5. Apply a relationship profile from the list on the main toolbar. (To create or change relationship profiles, see Managing how you view relationships.)
  6. To organize the entities in your custom diagram, from the Tools menu, click Grid Layout or click Hierarchical Layout.
  7. From the File menu, click Save or Save As.
    The custom diagram is saved.
    Note: At this point you can continue working with your new custom diagram in the Project Tree view and the Graphic view or you can choose the Edit > Build Custom Diagram... command to modify your custom diagram. If you want to work with many entities or many levels of usage, the Edit > Build Custom Diagram... command will be more convenient.

To explore your software system in a custom diagram, you can, for example:

  • Select or add different entities. To add entities:
  • drag them from the System Model in the Project Tree view or from the List view into the Graphic View of your custom diagram
  • Click the Add Uses or Add Users buttons on entities in the custom diagram. Add Uses or Add Users buttons are on source blocks that have relationships--move the mouse pointer over a block to see the buttons available.
  • modify your custom diagram with the Include list in the Edit > Build Custom Diagram... command. See Modifying a custom diagram.
  • Apply (and create) different relationship profiles. Two that are particularly useful with custom diagrams are included with Architect: Call graphs and Inheritance structure.
  • Use the block buttons (move the mouse pointer over a block to see the buttons available):
    Implements or Implemented by
    Overrides or Overridden by
    Add Uses or Add Users
    Extends or Extended by
  • Make Annotations
  • Open Source Files or Flowcharts
  • Do Searches
  • Compare one custom diagram to another

Modifying a custom diagram

The Edit > Build Custom Diagram command is a sophisticated tool that lets you manage what entities are included in the custom diagram and work through usage levels quickly and efficiently. To use the Edit > Build custom diagram command, you must have an existing custom diagram open and active in the Graphic view. The custom diagram must contain at least one entity that has been dragged in from the System model.

To modify (build) a custom diagram:

  1. Open a custom diagram in the Graphic view. If you do not have a custom diagram, create one with the File > New Custom Diagram command. See Creating a new custom diagram.
  2. Click Edit > Build Custom Diagram...
    The Build Custom Diagram dialog opens.
  3. From the drop down list at the top of the dialog, choose a custom diagram or model to serve as the basis for your custom diagram.
    Tip: To have your custom diagram contain all of the entities in the model, leave the Include and Exclude lists empty.
  4. (Optional) Add entities to the Include or Exclude lists. The Include and Exclude lists let you filter what entities will be in the custom diagram. To add entities to the Include or Exclude list, select the entities in the tree on the left and click the appropriate Add button. To remove entities from the Include or Exclude list, select them in the list and click the appropriate Remove button.
    • Children of entities in the Exclude list are not added to the diagram.
    • If the Include list is not empty, then only children of entities from the Include list are added to the diagram.
    • An entity that has parents in both the Include and Exclude lists is not added to the diagram.
  5. Select the Uses depth and Users depth values. See the table that follows.
    Click Build.

These values specify the depth of transitive closure of outgoing and incoming relationships, respectively.

If the depth is set to... the result is...
-1 the depth of transitive closure has no limit. All entities directly or indirectly connected with entities from the initial set are added.
0 nothing is added to the custom diagram.
1 only entities directly connected with the ones from the initial set are added
2 entities directly connected with the ones from the initial set and also entities directly connected with the entities directly connected with the ones from the initial set are added.
  ...and so on

An example of how to work with a custom diagram

To create a custom diagram representing a particular class and all of the class’s direct and indirect subclasses:

  1. Create a new custom diagram and drag the class you want to study into it.
  2. Apply the Inheritance Structure relationship profile.
  3. Click Edit > Build Custom Diagram...
  4. Set the Uses depth to 0 and the Users depth to -1.
  5. Click Build.

Viewing your source code

While you are working with custom diagrams or models, you can see your source code at any time from several convenient places in the Architect interface. When you click Show Source File, a view of the source code of the selected entity opens with its own tab in the right pane. The first line of code of the entity you selected is highlighted. For some entities, such as directories or classes, there are no source files and the command Show Source File is dimmed. You can click Show Source File from the following places:

  • Show sub-menu of the Entity pop-up menu (right-click any entity displayed in the Project Tree view or Graphic view to open the Entity pop-up menu, and go to the Show sub-menu)
  • Flowchart pop-up menu (right-click anywhere in a Flowchart diagram)
  • Search list pop-up menu (right-click any identifier in the Search tab of a List view)
  • Relationship Viewer pop-up menu (right-click any entity in the Identifier, in File, and uses Identifier columns while displaying relationship details, or right-click an entity in the uses Identifier or the in File columns while displaying interface details)
  • Differences list pop-up menu (right-click any item in the Differences list)

Note: C++ template names can be huge. MySQL truncates names longer than 255 characters and replaces the overrun with a unique hash of the string (a few dots and a number).

Editing custom diagrams and models

You can perform many types of editing operations on custom diagrams and models that you own, including:

  • creating architecture blocks
  • grouping, moving, exploding, expanding, contracting, renaming, and deleting entities
  • resizing blocks in the Graphic view

You can only edit a custom diagram or model you own. You cannot edit the System model or another user’s custom diagram or model, unless you save your own version first. See Creating a model based on an existing model. If you are viewing a read-only model such as the System model, a number of menu items are unavailable (for example, group, cut, paste, new block, etc.).

Note: Changes are made only to the custom diagram or model within Architect, not to your source code.

To edit a custom diagram or model:

  1. Optional: Open a Graphic view of the model that you want to edit. To do this, right-click the model name in the Project Tree view and click Open, or double-click any entity in the Project Tree view.
  2. Navigate to the architectural level that contains the entities you want to edit. You can also search for entities you want to edit. See Klocwork Architect search tips.
  3. Click on an entity in the Project Tree view or Graphic view to select it, or press the Ctrl key and click on several entities to select more than one entity. You can also click and drag the cursor over a group of entities in the Graphic view to select them.
  4. Use the commands on the Edit menu to edit the entities and change the diagram. These commands are described in the following sections.
  5. Click File > Save to save your changes to the model.

Creating architecture blocks

You can create architectural components (blocks) in the custom diagram or model of a specific system. You can use these virtual entities to experiment with different custom diagrams or models before creating actual entities in your software system.

Note: Grouping is another way of creating architecture blocks.

In C/C++ project user models, you can add class blocks only below the file level and directory or file blocks only above the file level. In Java project user models, you can add jar file, class file, or package blocks only above the file level.

If you are viewing a model based on a user-defined XML file, any entity type defined in that XML file appears as an available block type in the New Block dialog. For more information, talk to your Klocwork administrator or see Creating an XML custom diagram file or model file.

To create a virtual entity in a custom diagram or model, click Edit > New Block or right-click on an empty space in the Graphic view and select New Block. The block name may be a maximum of 80 characters. It can include symbols, except for the following: / " \ '

Note that it is possible to enter a name that is already used in this project build.

Renaming entities

You can rename any of the following in an Architect custom diagram or model:

  • directories
  • architecture blocks that have been created in Architect

In both custom diagrams and models, you cannot rename file-level entities that correspond to those in the actual software system or entities that correspond to those in the actual software system and have been placed within those file-level entities. In other words, you cannot rename source entities.

To rename an entity, right-click it and select Rename.

Moving entities

You can move entities by dragging them or by cutting and pasting.

Cutting and pasting entities

In a custom diagram, you can cut and paste entities as you choose, without regard for the hierarchy of your source software. In a model, you can cut entities within a file-level entity, but they may only be pasted into another file-level entity. Entities at or above the file level may be cut from one level and moved to another level of the architectural hierarchy.

Dragging entities

You can drag entities

  • from one location in the Project Tree view to another location in the Project Tree view
  • from the Project Tree view to the Graphic view
  • from the Search results list to the Project Tree view or Graphic view. See Using the Search list to move entities.
  • from the Relationship Viewer list to the Project Tree view or Graphic view. See Using the Relationship Viewer list to move entities.

Keep the following in mind when dragging entities:

  • You can move more than one entity at a time.
  • You cannot move a parent entity onto its child diagram.
  • In a model, you cannot move an entity into a file if that entity was not originally located inside a file. (In a custom diagram, you can.)

Sharing custom diagrams and models

You can specify whether other Architect users and Source Cross-Reference users can view custom diagrams or models you’ve created.

Notes

  • The Share command is only available if you are the owner of the custom diagram or model.
  • If you want to view your own models in Source Cross-Reference, you must share them first.
  • You cannot share custom diagrams with Source Cross-Reference users.
  • Other users' models are read-only, but you can save your own version of another user's model so that you can edit it.

To share your custom diagram or model:

  1. Click or right-click the custom diagram or model in the Project Tree view.
  2. From the File menu or the Model pop-up menu, click Share.
    When other users open the project in which you created your custom diagram or model, your custom diagram or model will now appear in their Available Models list for that project. Your models will now also be available for you to view in Source Cross-Reference.
    If you had previously shared your custom diagram or model and want to make it private, click File > Share again.

Tip: To find out whether you’ve shared a custom diagram or model, right-click the custom diagram or model in the Project Tree view. If a checkmark appears beside Share, the custom diagram or model is shared.

Note: Other Architect users must refresh their Project Tree view to see your shared custom diagrams and models. Creating a new custom diagram or model or re-opening a project build refreshes the Project Tree view.

Comparing two custom diagrams or two models

Once you have edited a model, you can compare it with the System model or another model (including other users’ models). Architect gives you a list of the changes that must be carried out on the existing model to make it conform to the target model. You can use this list as a guide for what changes you need to make to the software system itself. You can also compare two custom diagrams.

You can also export a list of differences in text format.

It is important to note that generating a list of differences when Model A is active, and selecting Model B in the Generate Differences dialog, does not produce the same results as generating a list of differences when Model B is active, and selecting Model A in the Generate Differences dialog. The list of differences in the first case is a list of operations you must perform on Model A to convert it into Model B. The list of differences generated in the second case is a list of operations you must perform on Model B to convert it into Model A.

For example, say you create Model B based on Model A. You then add file xyz.C to Model B. If you generate a list of differences when Model A is active, the list of differences looks like the following:

Operation Entity Kind Source: Model A Target: Model B
Add xyz.C FILE   toolbus/xyz.C

On the other hand, if you generate a list of differences when Model B is active, the list of differences looks like the following:

Operation Entity Kind Source: Model B Target: Model A
Delete xyz.C FILE toolbus/xyz.C  

To compare two models:

  1. Select the model you want to use as the basis for comparison (for example, the System model) in the Project Tree view or the Graphic view. This model is known as the source.
  2. Click Tools > Compare With....
    The Generate Differences dialog appears.
  3. In the list of available models, select the model that you want to compare. This model is known as the target. Click OK.
    The Architect progress bar displays the text "filling table" while the list is generated.
    The list of differences appears in the list pane under a tab titled "Differences".

Reading the Differences list

The Differences list consists of five sortable columns:

Operation: the operation that must be carried out on the base model to achieve the target. Possible operations are Add, Delete, Move, and Rename.

Entity: the entity that the operation in Column 1 must be performed on.

Kind: the entity type of the entity in Column 2.

Source: <source custom diagram name> or <source model name>: the custom diagram or model that was active when you clicked Tools > Compare With... (typically the System model, or the custom diagram or model that you want to edit).

Target: <target custom diagram name> or <target model name>: the custom diagram or model you selected in the Generate Differences dialog (typically the custom diagram or model that you have edited).

Tip: Click any identifier in the Differences list and click Show Architecture to show where the selected entity is located in the software system architecture.

Tip: You can sort information in List views by clicking any of the column headers. The Sort arrow indicates which column has been used for sorting, as well as the direction of the sorting.

Example: Comparing two models

In this example, using the Architect modeling capabilities, we have created a model called Simplified_model_1. We have refined it to the state where we’re ready to apply the model to our software system. We have organized the files into modules to simplify the structure. We would like a list of operations to carry out on our actual source code to make it resemble the simplified model.

Here is the original System model:

Architect system view for diff.jpg

Here is our simplified model:

Architect simplified model for diff.jpg

To obtain a list of differences between the simplified and our software system, we need to do the following:

  1. Select the System model in the Project Tree view or the Graphic view.
  2. Click Tools > Compare With....
  3. In the Generate Differences dialog, click Simplified_model_1.
    Architect generate differences dialog example.jpg
    The list of differences appears.
    Architect differences list example.jpg
    We can now read the differences list from left to right to find out what operations need to be carried out on the software system. For example:
    • The first line in the screen above indicates that we need to add the entity main, which is a directory, to the location toolbus/main.
    • The bottom line in the screen above indicates that we need to move the entity tbEvents.C, a file, from toolbus/tbEvents.C in the System model to toolbus/Misc/tbEvents.C in the model Simplified_model_1.
  4. We can also export our list of differences as a semi-colon-delimited text file by clicking Export Architect export icon.gif in the List view toolbar.

Printing or saving the Graphic view

You can use File > Print to print or save to a file. When saving to a file, if you specify only a file name, the file will be saved in your Architect installation directory.

The complete diagram of the architectural level you are currently viewing in Architect is printed. To print views of other levels of the system architecture, navigate to a different architectural level and print again.

Tips on viewing your printed output:

  • Disable two-sided printing while you print the Graphic view.
  • When you print the Graphic view, numbers are inserted at the right, left, top and bottom margins of the pages. Join the number 1 on the right side of the first printed page with the number 1 on the left side of the second printed page, and so on.

Deleting custom diagrams or models

You can delete any custom diagram or model that you own.

Caution: Once you've deleted a custom diagram or model, it cannot be retrieved.

Note: If you delete a custom diagram or model that was shared, a file with the name (for example, <model_name>.xml) will remain in the Custom Diagrams or Models directory for the build. It can safely be deleted.

To delete a custom diagram or model, right-click the custom diagram name or model name in the Project Tree view and click Delete Model.

See also