API Tutorial 1: Writing Your First API Script

This article is part of a series on using the Understand API.

Understand has an extensive API to let you query the data it captures about your code. It has three flavors: Perl, Python and C. The Perl API is more robust than the other two as it allows interaction with the Understand GUI and doesn’t require additional setup. All three APIs are read-only, they do not modify the Understand project. If you need to do that programmatically, take a look at ‘und’. There is also a Java API that was written as part of creating the Understand Eclipse Plugin. However it is more light weight it does not have the full capabilities of the other APIs.

Opening An Understand Project

Let’s start by taking a look at a very simple Perl API script.

sample.pl

use Understand;
$db = Understand::open("c:\\projects\\test.udb");
foreach $file ($db->ents("file")) {
print $file->longname(),"\n";
}

The first line tells the Perl interpreter that you want to use the Understand API library. It then opens an Understand project file (c:\projectstest.udb) and iterates through a list of each of the file entities in that project and prints the name of each file on a separate line.

To run this yourself, change the path to point to one of your own projects. Note that for Windows paths you need to escape the slashes by doubling them.

Uperl is a perl interpreter that is included with Understand in the bin\system directory. To run this script, open the command line/terminal and run:

cd “c:\program files\scitools\bin\pc-win64” or the appropriate path on your system
uperl.exe myscript.pl

Here is the same script for the Python 3 API. Python needs to be installed on your system and the Understand Python libraries setup correctly.
sample.py

import understand
db = understand.open("c:\\projects\\test.udb")
for file in db.ents("file"):
print(file.longname())

And again, the exact same thing in the C API.

sample.c

#include <stdio.h>
#include <stdlib.h>
#include "C:\\Program Files\\SciTools\\src\\udb\\udb.h"
static char *dbFilename = "c:\\projects\\test.udb";
main ( int argc, char *argv[]) {
UdbStatus status = udbDbOpen(dbFilename);
UdbEntity *ents;
int entsSize;
int i;
udbListEntity(&ents, &entsSize);
udbListEntityFilter (ents, udbKindParse("file"),
&ents, &entsSize);
for (i=0; i<entsSize; i++) {
printf ("%s\n", udbEntityNameLong(ents[i]));
}
udbListEntityFree(ents);
udbDbClose();
}

Makefile

sample.exe : sample.obj

Due to the size of the C API samples, the rest of these tutorials will only show samples from Perl and Python. For more information and details specific to the C API, see the API manual.

Quick Start Scripts

I prefer to start most of my scripts from a template that contains all of the “regular” stuff. This helps me focus just on the core of what I want to accomplish. Additionally, for Perl, if the script is being run from the GUI, than the script automatically grabs the open project. Here are zipped files of the templates I usually start with:

Perl Template: PerlTemplate

Python Template: PythonTemplate

C API Sample Project: sample.zip

 

Next, part 2: Entities, References and Filters