API Tutorial 4: Graphs

This article is part of a series on using the Understand API (Part 1, Part 2, Part 3).

The ability to draw custom graphs is a core feature of the Understand PERL API. Using the Understand Plugin system, advanced users can develop their own custom graphs addressing specific information needs. More information about graphs and setting options in graphs

 

Building a Call Tree Graph

We needed a way to visualize functions calls. Here was my process in creating this simple yet powerful graph. You can download the completed plugin here.

To install a plugin, simply drag the .upl file into the Understand GUI, or you can manually place it in one of the following locations:

Windows – e.g. C:\Program Files\SciTools\conf\plugin\User\IReport
Mac – e.g. /Users/username/Library/Application Support/SciTools/plugin/IReport
Linux – e.g. /home/username/.config/SciTools/plugin/IReport

Start by creating a new plugin file call_tree.upl you can start from an empty file, or you can modify the Graph Template which is a simple example with a lot of explanatory comments.

The first part of creating the plugin is some setup. We use base Understand’s simplified version of Graphical Visualization Software. Visit graphviz for detailed documentation.

The next two lines will be discussed later in this tutorial.

 

Next we create a required subroutine name that defines the name of our graph. When an entity is right-clicked, say a function, the name of our graph appears in “Graphical Views” of the contextual menu.

 

 

Now we create another subroutine test_entity that tests which kind of entities our graph knows about. For this graph we only care about functions that are not unknown to a database project and not unresolved. Here is more information on kind filters.

 

Next lets create another required subroutine init which will only be called once.  Understand gives you the ability to change the way graphs look and behave, so I wanted the option to change the depth of my tree. The option is defined in $graph->options->define(...); where $max_depth ( at the top of our code ) is the string to define the submenu. The item selected by default is 3.

 

The last required subroutine is do_load. This is where Understand actually runs the graph. If this is called for an entity, $entity is set to the Understand::Ent object. I initialize $current_depth to 1 because our tree starts at the root node of the entity. The next line sets direction of graph layout. For example, if rankdir=”LR”, and barring cycles, an edge T -> H; will go from left to right. By default, graphs are laid out from top to bottom. The last line calls build_tree which creates nodes and edges of the tree.

 

Finally, the last subroutine build_tree is initially called to receive a parent of 0 and the current depth of 1. A new node is created with the associated $entity and the $entity->name( ) Understand nodes will automatically link to the Entity if passed an Understand::Ent object. Then an edge is created from the parent to the child node if the parent exists. $entity->refs( "call", "",1 ) returns a list of entities called from$entitybuild_tree recursively gets called with a new parent node being the referenced called entity.

 

That’s it. You should be able to right click on a function and select Graphical Views->Call Tree and see your graph! If it doesn’t show up you can use uperl -c call_tree.upl from the command line to see if there are any syntax errors.

What graphs will you think of to add?

 

Next Tutorial: Interactive Reports