Using the Application Diagram

What to do next

The Application Diagram viewer opens up in the editor area of the workbench. The viewer is made up of a main canvas and a palette. The main canvas shows either the Source Call Diagram, Program Structure Diagram, or both depending on what was initially selected. The diagrams are made up of nodes and connections. The nodes represent the various artifacts in your application and connections represent relationships between those artifacts. Each node is given a label based on its underlying source artifact or object name.

In a Source Call Diagram, the expandable nodes represent source members, the nonexpandable nodes represent blocks of code within the source that can be called, such as RPG subroutines, RPG subprocedures, COBOL procedures, CL procedures, CL subroutines, and main entry points. The connections represent calls between the blocks of code. For example, if your ILE RPG source member contains subroutines placeOrder and validateAdr and the placeOrder subroutine calls the validateAdr subroutine, the diagram would contain the following image:

Source Call Diagram

In a Program Structure Diagram the nodes represent programs and service programs. For ILE programs and service programs the nodes contain a list of the bound modules. Clicking on the plus sign in the upper left corner expands the list of modules (only applicable if the program or service program contains more than one module). When the list of modules is expanded, clicking on the minus sign collapses the list. The connections in a Program Structure Diagram represent binding relationships between objects. For example, if program ORDER was bound to service program VALIDATE, then the diagram would contain nodes labeled ORDER and VALIDATE with a connection going from the ORDER node to the VALIDATE node (representing that ORDER binds to VALIDATE).

By default, the Application Diagram opens up to show both types of diagrams, so if you selected source members and programs / service programs as input then you will see the Source Call Diagram and Program Structure Diagrams at the same time. You can switch to seeing only one diagram by right-clicking on a blank section of the diagram and selecting one of the Switch View cascading menu options.

Switch view of the Source Call Diagram

If the Application Diagram preference setting Lay out the diagram automatically is checked, the diagram is automatically rearranged after switching the view. The source members are initially displayed as collapsed in most cases. When collapsed, the source member node displays the number of children nodes that it contains. You can expand it to see the children nodes. This gives you a high-level view of your application and allows you to drill down to see the details. For convenience, if you only have one source member in your selected resources to launch the Application Diagram and that source member has less than 100 children nodes, the source member node is expanded by default. If the source member has only one child node, the child node is always displayed without option to collapse and expand.

When you select a node in the diagram, the node is highlighted with a blue border, all the inbound connections are highlighted in red and all the outbound connections are highlighted in green. When you select a connection in the diagram, the connection is highlighted in blue, the node at the source end of the connection is highlighted in red and the node at the target end of the connection is highlighted in green. Whenever you hover the mouse over a node or connection the item is temporarily highlighted with an orange border and a tool tip appears to provide more information for the item.

Some connections span source and program structure artifacts and therefore require both the Source Call Diagram and Program Structure Diagrams to be showing ("All"). For example, the application diagram shows program calls from RPG, COBOL and CL source members. This is represented as a program call connection that starts at the subroutine or subprocedure making the call and terminates at the program object being called.

Some connections are displayed dynamically. These connections are called as aggregate connections. An aggregate connection represents all subroutine, subprocedure, and program calls between two nodes. They are displayed when the nodes are collapsed and disappear when the nodes are expanded. For example, a procedure in a source member calls a program. When the source member node is collapsed, an aggregate relationship is drawn between the source member node and program node. When the source member node is expanded, the aggregate connection disappears and a connection from the procedure node of the source member to the program node is drawn.

Outline view

You can use both the Outline and Properties views with the Application Diagram viewer. The Outline view initially shows a thumbnail view of the entire diagram. This can be useful when the entire diagram does not fit within the visible space of the viewer.

Application Diagram Thumbnail view

The thumbnail view will show the entire diagram along with a shaded box that represents the part of the diagram that is currently visible in the viewer.

Application Diagram Outline view

Using the mouse you can drag this shaded box around the thumbnail view to position the viewer. The Outline view also contains a text view that lists the sorted names of all the nodes in the diagram. This text list is useful when you want to find a specific node in the diagram, simply select it in the list and the viewer is repositioned so the node is visible. Use the icons in the outline view's toolbar to switch between the thumbnail and text views.

Properties view

The Properties view shows additional information for nodes and connections selected in the Application Diagram. For some nodes the Properties view contains multiple tabs, with each tab showing different types of information. By default the Properties view opens in the bottom left corner of the Remote System Explorer perspective, but this area does not provide sufficient horizontal space for some of the tables displayed in the Properties view when using the Application Diagram. Drag and drop the Properties view to the group of views that contains the Object Table View (to the immediate right) in order to avoid having to scroll horizontally.

Application Diagram Properties view

To open the Properties view, right-click white space in the main canvas and select Show Properties View.

Actions

You can edit or browse the source for some of the nodes in the Application Diagram such as modules, RPG subroutines and subprocedures, and COBOL procedures. Double clicking on the node automatically opens the editor to edit the source. Alternatively, you can right-click and select either Edit Source or Browse Source from the pop-up menu.

You can also double-click on connections that represent subroutine, subprocedure, procedure, and program calls to have the source for the calling node opened in the editor and positioned to the line where the call is performed.

You can expand or collapse the source member, program, or service program nodes. To expand a node, select the node, and click the + icon on the node. To collapse a node, click the icon on the node. Alternatively, you can right-click and select the Expand or Collapse menu to expand or collapse the node. You can also press a key combination to expand or collapse a node. The default keys are Ctrl+Alt+E for expanding, Ctrl+Alt+C for collapsing. These keys can be customized from the Preferences page. If you want to expand or collapse all container nodes, right-click white space on the canvas and select the Expand All or Collapse All menu.

You can ask the diagram to arrange itself. To do so, right-click white space and select Arrange All. You may still need to adjust the positions of the connections and nodes manually to make the diagram more readable. You can also arrange the child nodes of a single source member. To do so, select the source member node, click the white space inside the source member node, right-click, and select Arrange All.

Palette

The Palette view contains tools for zooming and adding notes to the diagram. The palette can be minimized and maximized by clicking on the black triangle in the upper right corner of the palette. If you would prefer to use the Workbench's Palette view instead of the palette embedded inside the viewer then open the full palette view (Window > Show View > Other) and the embedded palette will disappear. Closing the full Palette view causes the embedded palette to reappear.

When using the Zoom tool from the palette, you zoom in by left clicking and zoom out by holding down the Shift key and left clicking.

Adding notes to diagrams

You can add documentation to the generated Application Diagrams by adding notes to it from either the context menu or palette. The notes can either be standalone or attached to a node or connection in the diagram. To add a note to a node first select the node and then right-click and select Add Note from the pop-up menu. You can then enter a description for the node in the attached note. In order to keep notes, you must explicitly save the diagram. If you close the diagram without saving it then all notes will be lost.

When you use Switch View to switch diagrams, a note added in a previous diagram is still visible. However, the note connection is visible only when the artifact that note attaches to is visible. For example, you currently work on the Source Call Diagram and add a note attaching to a source member node. Then you switch to Program Structure Diagram. The note is still visible but the connection from the note to the source member node is disappeared because the source member node is not visible in the Program Structure Diagram. When you switch back to the Source Call Diagram, the note connection is displayed again.

Application Diagram preferences

Windows > Preferences > Application Diagram page lets you specify which view is visible when the Application Diagram is first opened and the default line style and orientation to use. You can also open this preference page from the diagram by right-clicking the white space of canvas and selecting Preferences > Application Diagram.

Application Diagram Preferences page

The Window > Preferences > General > Appearance > Colors and Fonts preference page lets you customize the font, incoming connection or source node highlight color, and outgoing connection or target node highlight colors used by the Application Diagram. To open this preference page from the diagram, right-click on the white space of the canvas and select Preferences > Colors and Fonts.

Application Diagram color and fonts

Window > Preferences > General > Keys allows you to customize the key combinations for expanding and collapsing the container node for Application Diagram.

Line style and orientation

When the application diagram first opens, it attempts to lay out the diagram in a way that makes it the most readable. You can configure how the diagram is laid out through the line style and orientation settings. The choices for line style are either Oblique or Rectilinear. The Oblique line style draws connections between nodes taking the shortest route possible while attempting to avoid having lines that intersect other nodes.

Application Diagram Oblique style horizontal orientation

Often this results in lines that are diagonal. The Rectilinear line style draws connections between nodes using only horizontal and vertical lines.

Application Diagram Rectilinear style vertical orientation

The choices for orientation are horizontal and vertical. A horizontal orientation draws the diagram starting at the left and growing as required to the right. A vertical orientation draws the diagram starting at the top and growing as required to the bottom.

The default line style and orientation are Oblique and Horizontal. The defaults can be changed on the Application Diagram preference page. The settings can also be changed for a single diagram by right-clicking a blank section of the diagram and selecting the Change Layout action from the pop-up menu.

To improve readability you can rearrange nodes and connections after the diagram has been drawn. You can drag and drop nodes to change their location. Connections to and from the node are automatically updated. You can drag and drop connection lines to route them around nodes. Select the point on the connection line that you want to move, then drag and drop it. This inserts a new bend point into the line. Layout customizations are lost if you change the layout style or orientation or select the Arrange All action. To save your customized layout and avoid losing your changes, save your diagram before you close it.

The layout of child nodes of a source member node may be lost after collapsing and expanding again, depending on the preference setting. If Lay out the diagram automatically is checked, the child nodes are rearranged when expanding. If this preference is not checked, the previous layout of child nodes is preserved.

Saving the Application Diagram

The Application Diagram can be saved to a workspace file, an image file or a text file. Saving to a workspace file allows the diagram to be reopened at a later time. Saving to an image file allows the diagram to be easily sent to another person or embedded within another document. Saving to a text file allows the information from the diagram to also be saved for later reference, easily copied, or searched using a text search.

To save the diagram to a workspace file, use the workbench's File > Save As menu. This prompts you for a folder inside of the local workspace and the filename to save the diagram as.

Application Diagram Save As

Saving the diagram creates two files: a filename.appmdl file and a filename.appmdl_diagram file. The first file contains the model generated by the Visualize Application Diagram action. The second file contains the layout information and any notes you have added to the diagram. Double click the filename.appmdl_diagram file to re-open the saved diagram.

To save the diagram to an image file or text file, right-click on any blank section within the diagram and select the appropriate action from the pop-up menu's cascading File menu. Both allow you to save the file outside of the current workspace. You can also save a part of the diagram to an image file by first selecting all nodes and connections you would like saved and then selecting the File > Save As Image File from the context menu of any of the selected nodes or connections.

Find Main Entry Point

When there are many nodes and lines in the Source Call Diagram, it is not easy to find out the main entry point. You can right-click on any white space within the diagram and select Find Main Entry Point from the context menu. The main entry point node will be found and highlighted. If the main entry point is inside a collapsed source member node, the source member node will be expanded and the main entry point node will be found and highlighted. If more than one main entry point is found, you will be prompted with a dialog that lets you choose the main entry point that you want to look at.

Print Diagram

You can print the diagram from the workbench menu or from the context menu of the diagram. To print a diagram from the workbench menu, select the File > Print from workbench menu. To print a diagram from the context menu, right-click on any white space within the diagram and select File > Print from the context menu.

Legend of icons
Table 1.
Icon Description
Viewer and Visualize icon Application Diagram viewer and visualize action
Source member icon Source member
Main entry point icon ILE RPG, ILE COBOL, or ILE CL main entry point
subprocedure or procedure icon ILE RPG subprocedure or COBOL procedure
RPG subroutine icon ILE RPG or ILE CL subroutine
Program object icon Program object
Service program object icon Service project object
Module bound icon Module bound into a program or service program object

Feedback