B.2 Setting up a Database

The Input Deck database must be set up similarly to conventional databases. First the database has to be initialized. This is done by a call to ipdInit

bool ipdInit(const char *pathList, FILE *logFile);

The Function ipdInit takes two arguments. The first argument is a string which contains a list of paths to look for input files. The paths are separated by semicolons or colons. The second argument must be a valid file handle to a logfile, to which the logging information is written to. If no logging information should be written logFile must be set to 0. To write the logging information to standard output stdout has to be used instead. ipdInit returns true in case of success and false in case of an error.

After initialization any number of databases can be created using the function ipdCreateBase:

long ipdCreateBase(const char *name, long hashSize);

It takes two arguments, the name of the database and the size of the internal hash. The first argument is mandatory, the second may be set to 0 to use the default setting. The hash size of the internal hash should be set if the amount of items can be estimated. The hash size should be a prime number and at least three times higher than the number of items used [117] for performance reasons. ipdCreateBase returns a valid identification number for the created database or 0 in case of an error.

Any number of databases can be created, but all methods of the application interface refer to the active one. When a database has been created by a call to ipdCreateBase it is made active. To switch to another database the function ipdSetBase has to be used. It takes one argument which is the identification number returned by a previous call to ipdCreateBase when the particular database has been created.

bool ipdSetBase(long index);

The function returns true in case of success and false in case of an error.

Items may be created, queried, and modified. Normally, an input file is read to load the database information. This is done by a call to ipdReadInputDeck which simply requires the file name of the file to load. Although it is not common practice several files can be merged by loading them one after the other. Therefore, the files must not contain definitions of the same variables or sections. The function ipdReadInputDeck returns the number of successfully parsed files and 0 in case of an error. The number returned is greater than 1 if the file loaded included several other files.

long ipdReadInputDeck(const char *filename);

After usage a database has to be closed by a call to ipdFreeCurrentIpd which closes the active database. To close all databases the function ipdFreeAll is used. Since the Input Deck database may contain several large trees which are build up using dynamic allocated memory freeing all pieces of memory can take a long time. Therefore, to free all allocated pieces of memory ipdFreeAll only frees the chunks of the memory management of the Input Deck database (see Section 3.5.3.3) which is very fast. Nevertheless another function ipdFreeAllInDetail is implemented for debugging reasons which frees each piece of memory separately. The function declarations are given by

void ipdFreeCurrentIpd(void);
void ipdFreeAllInDetail(void);
void ipdFreeAll(void);

A typical sequence of calls to set up and to close an Input Deck database is shown below for one database.

ipdInit("~/vproject/mmnt/defaults/", NULL);
ipdCreateBase("MyInputDeck", 0);
if (ipdReadInputDeck("myfile") > 0)
{  // working with the database.
   // ...
}
ipdFreeAll();