Using the C API

## Code Sample Using the C API

###

The following simple code sample opens an Understand database, reports a couple of project metrics, a list of function names and a reference for where the function is defined, and then closes the database.

The API calls have been bolded for illustration.

     /* sample program using Understand C API */
     #include <stdio.h>
     #include <stdlib.h
     #include "../sti/src/udb/udb.h"

     main(
       int argc,
       char *argv[])
     {
        UdbEntity    *ents;               /* list of entities */
        int          entsSize;            /* number of entities */
        UdbReference *refs;               /* list of references for entity */
        UdbReference *filterrefs;         /* list of filtered references for entity */
        int          i;                   /* counter */
        UdbStatus    status;              /* return status */

        /* set Understand license location */
        udbSetLicense("c:\\program files\\sti\\conf\\license");

        /* open Understand database */
        status = udbDbOpen("sample.udc");
        if (status)   {
           printf ("unable to open valid Understand database: %s ", "sample.udc");
           switch (status)    {
              case Udb_statusDBAlreadOpen:
                              printf("database is already open\n");                break;
              case Udb_statusDBOldVersion:
                              printf("database is old version\n");                 break;
              case Udb_statusDBUnknownVersion:
                              printf("database is unknown version\n");             break;
              case Udb_statusDBUnableOpen:
                              printf("unable to locate database\n");               break;

              case Udb_statusNoApiLicenseAda:
                              printf("no Understand/Ada license available\n");     break;
              case Udb_statusNoApiLicenseC:
                              printf("no Understand/C license available\n");       break;
              case Udb_statusNoApiLicenseFtn:
                              printf("no Understand/Fortran license available\n"); break;
              default:        printf("unable to access database\n");               break;
            }
            exit (EXIT_FAILURE);
        }
        /* get list of all entities */
        udbListEntity(&ents, &entsSize);

        /* report on some project metrics */
        printf ("Entities in Project: %d\n", entsSize);
        printf ("Files in Project: %d\n", udbMetricProject(Udb_cProjMetricCountFile));
        printf ("Functions in Project: %d\n",
                                       udbMetricProject(Udb_cProjMetricCountFunction));

        /* filter list to include only non-member object kinds */
        udbListEntityFilter (ents,
                             udbKindParse("object ~member"),
                              &ents, &entsSize);
        /* loop through all the list of filtered entities */
        for (i=0; i<entsSize; i++)   {
           printf ("%s\n", udbEntityNameLong(ents[i]));

           /* get references  for this entity */
           udbListReference(ents[i], &refs, NULL);
           /* filter the references to the desired kinds (in this case, where defined)*/
           udbListReferenceFilter(refs,
                                  udbKindParse("definedin"),
                                  NULL,
                                  0, &filterrefs, NULL);

           /* output reference info if reference of specified kind is found */
           if (filterrefs != NULL && filterrefs[0] != 0)	   {
                printf ("   %s: %s in %s at line:%d \n\n",
                         udbKindShortname(udbReferenceKind(filterrefs[0])),
                         udbEntityNameShort(udbReferenceEntity(filterrefs[0])),
                         udbEntityNameShort(udbReferenceFile(filterrefs[0])),
                         udbReferenceLine(filterrefs[0]) );
                /* free the filtered ref list, if any */
                udbListReferenceFree(filterrefs);
                }
           /* free the ref list for the entity */
           udbListReferenceFree(refs);
           }
        /* free the entity list */
        udbListEntityFree(ents);
        /* close Understand database */
        udbDbClose();
        }
     exit (EXIT_SUCCESS);
     }

Scientific Toolworks, Inc. http://www.scitools.com Voice: (802) 763-2995 Fax: (802) 763-3066 support@scitools.com sales@scitools.com