In
this section we will discuss another auxiliary package getpars. This is a
simple package for inputting parameters by keyword. It is crucial to reading
and interpreting the parameter file, and to storing the various parameters
specified in it. The package uses a "handle" (object) to store
parameter information, and provides a simple string replacement facility.
Parameters may appear in any order in the parameter file. Multiple parameter
files can be dealt with, though the need for this would be unusual.
We
will briefly outline the various functions that are part of this package:
1. phandle
*openpars(char *fname) : Opens handle, and must be called before all other
routines.
Sample
call: ph = openpars(myparameterfilename)
;
In
all of the following parameter setting routines, if the parameter is not
present, the variable to receive the value will not be changed. Thus default
values should be set before the call.
2.
int getstring(phandle *pp, char *parname,
char **kret) ;
Sample
call: getstring(ph, "inputfilename:", &inputfilename) ;
Return
value: positive integer if parname is
found (and therefore kret is set)
else negative integer. This is the same for all the analogous routines
discussed below.
3.
int getint(phandle *pp, char *parname,
int *kret) : Sets an integer value. YES or NO values can be interpreted as
1, 0 respectively. This is convenient for setting boolean switches using
"c" ints.
Sample
call: getint(ph, "iterations:", &iterations) ;
4.
int getints(phandle *pp, char *parname,
int *aint, int nint) : Sets nint integer values into array aint.
The values can be separated by white space or ':'.
5. int getintss(phandle *pp, char *parname,
int *aint, int *xint) : Sets variable number of integer values into
aint. Number set is returned in xint.
6.
void *closepars(phandle *pp) : This is a destructor,and is called
when parameter cracking is complete. All memory associated with ph is freed.
7.
void dostrsub(phandle *pp) : We use
the convention to insist that parameter names are lower case alphanumeric, and contain no upper
case parameters. Now upper case
"parameters" can be used for string replacement.
Example:
parameter file mypars contains:
HOME: /home/harvey01/nickp
datafile:
The following code fragment would be
appropriate:
ph
= openpars("mypars") ;
dostrsub(ph) ;
getstring(ph,
"datafile"; &datafilename) ;
closepars(ph)
;
8. void
writepars(phandle *pp) : writes a
copy of the parameter file (after string replacement if dostrsub has been
called) to standard out.