Support

Understand includes a PERL API which allows you to directly query the Understand database. If you want to create your own report, or gather information in a manner that we didn’t foresee in Understand, you can access the information yourself via the API. The API can be accessed in several different ways: most of the scripts are designed to be run from Understand’s GUI on the currently opened database. They can also be run from the command line, and some plugins are designed to interact directly with Understand.

Run Scripts in Understand

To run a script from inside of Understand, use Tools->Run a Command, configure any necessary parameters, and hit run. The resulting output can then be double-clicked to visit the referenced source.

 

Run Scripts from the Command Line

Scripts can be run from the command line using uperl, a special PERL executable included in Understand’s bin directory. To run a script from the command line, specify the script, the database and any options:

uperl scriptName.pl -db myproject.udb [Options]

So to run this same script from the command line, you could use the following command:

 

If you would rather access the Understand API from your own customized Perl 5.10.0 installation, just add <SciTools>/bin/pc-win32/Perl/STI to your Perl include path on OSX the default path to uperl is /Applications/Understand.app/Contents/MacOS/uperl. On non-Windows systems, you will also need to create an STIHOME environment variable that points to the <SciTools> directory. Keep in mind if using your own installation, that it will need to have thread support since our Understand Perl module is built with thread support. For example, when using Perlbrew, install it with this command: perlbrew install perl-5.10.0 -Duseithreads to build it with thread support, making it compatible with our perl module.

Use Understand Plugins

Plugins are special Perl scripts written specifically to interact with the Understand GUI. You can quickly tell them apart by the file extension: regular scripts use .pl while plugin scripts use .upl. Plugins give you the power to interact with specific entities inside of Understand, for example you can right click on an entity and run a custom (interactive) report on it, or generate your own graph.

Plugins are installed by dragging and dropping them into the Understand GUI or placing them in the Scitools/conf/plugins folder. Once installed they will show up in the context menu or in the main menu depending on the type of plugin.

Several of the graphs included in Understand are actually plugin scripts as well, including the control flow graph and the butterfly graph. They can be customized, or used as a starting point for creating your own graphs.

Write Your Own Scripts

Here is a collection of tutorials on getting started with the API. For more details, refer to the Perl API documentation under the Help menu in Understand, or here.

Sample Scripts

The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/perl folder.