Appendix B C API Code Samples

## Open Database and Get All Entities

### Description

This example shows a sample main() function, where the sample database is opened and closed.

This main() function can be used as a starting point for any of the other functional examples provided.

### Sample Code

     1
     2	 #include <stdio.h>
     3	 #include <stdlib.h>
     4	 #include "udb.h"

     5	 static char         *dbFilename = "test.udc";
     6
     7	 main ( int argc,  char *argv[])    {
     8	    udbSetLicense ("c:\\Program Files\\sti\\conf\\license");
     9	    status = udbDbOpen(dbFilename);
     10	    if (status)  {
     11	       printf ("unable to open  Understand database: %s \n", dbFilename);
     12	       switch (status)  {
     13	          case Udb_statusDBAlreadyOpen:
     14	                         printf("database already open\n");                    break;
     15	          case Udb_statusDBCorrupt:
     16	                         printf("database is corrupt\n");                      break;
     17	          case Udb_statusDBOldVersion:
     18	                         printf("database is old version\n");                  break;
     19	          case Udb_statusDBUnknownVersion:
     20	                         printf("unknown version\n");                          break;
     21	          case Udb_statusDBUnableOpen:
     22	                         printf("unable to locate file\n");                    break;
     23	          case Udb_statusNoApiLicenseAda:
     24	                         printf("no Understand Ada license available\n");      break;
     25	          case Udb_statusNoApiLicenseC:
     26	                         printf("no Understand C license available\n");        break;
     27	          case Udb_statusNoApiLicenseFtn:
     28	                         printf("no Undertstand Fortran license available\n"); break;
     29	          default:
     30	                         printf("unable to access database\n");                break;
     31	       }
     32	       exit (EXIT_FAILURE);
     33	    }
     34	    /* call any of the example functions here */
     35	    udbDbClose();
     36	 }

### Explanation of Sample Code

This example shows what is needed in order to call the API functions and how to open and close a database.

line 3: Include "udb.h" in order to use the Understand C API.

line 4: For demonstration purposes, the Understand database name being used is "test.udc". Change this name to specify the name of the Understand database that you have already created and analyzed.

line 7: Call udbSetLicense() to specify directory path to the Understand license file to use. The license is not consumed until the call to udbDbOpen() is performed. The call to udbSetLicense() is optional. The API will attempt to locate a license file in the following order:

     1. udbSetLicense()
     2. environment variable STILICENSE
     3. For Windows, the STILICENSE key in
          HKEY_CURRENT_USER\Software\ Scientific Toolworks, Inc.
     4. conf/license inside sti home directory

lines 8-21: Open the Understand database and check the return status. The return status will indicate if the database cannot be opened for any reason, including if a license cannot be obtained.

line 24: Call any of the other example functions provided here or one of your own creation.

line 25: Close the database.

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