param.vtme

speech signal process tools

internal symbol table from which parameter values can be retrieved.  
.i Read_params
has various parameters to specify the name of the parameter file, to
control whether or not ESPS common is processed, and to control whether
or not rule (4) (Section 2.1) is to be enforced.  For example, the
call
.vS 
.nf

    /*sd_file is the name of an input SD file*/
    read_params("params", SC_CHECK_FILE, sd_file);

.fi
.vE
specifies that the parameter file is "params" (the ESPS default
convention), and that the ESPS common file is to be processed provided 
that its "filename" entry matches the contents of the variable
"sd_file".   Similarly, 
.vS 
.nf

    read_params("params", SC_CHECK_FILE, NULL);

.fi
.vE
processes the parameter file and the common file without regard to 
any "filename" entry in the common file.  
.lp
.i Read_params
detects following types of errors:  
.(l
neither parameter nor common file can be opened (returns -1)
File contains syntax errors
Symbols multiply defined
Type conflicts
.)l
If the parameter and possibly the common file are opened successfully,
.i read_params
attempts to process them entirely even if errors are encountered,
printing appropriate messages on the standard error output.  Each syntax
error message indicates the line of the parameter file where it
occurred.  However, a program exit will occur after processing is
complete if any errors were present in the file.  The routine either
returns successfully, in which case a symbol table is built, or the
program exits.  
.sh 2 "Reading Parameter Values"
.lp
Once the internal symbol table has been built by calling 
.i read_params,
programs can retrieve the values of specific symbols by calling 
the various "getsym" library routines noted in the following table:
.nf

.TS
box,center;
c s
c | c
l | li.
Reading Parameter Values
_
Type of Symbol	Program to Call
_
int	getsym_i
double	getsym_d
char	getsym_c
string	getsym_s
int array	getsym_ia
double array	getsym_da
.TE

.fi
.lp
As described earlier, if the parameter file indicates that the symbol is
indefinite, the user is prompted for a value.  The default value is used
if the user types a RETURN in response to the prompt.  
.lp
If, for any of the routines described above, the requested symbol is
undefined or has the wrong type, an error message is printed on the
standard error output and a zero or null value is returned.  The symbol
table module keeps track of errors; the routine 
.i symerr_exit
(3\-\s-1ESPS\s+1), which takes no arguments and returns no value, causes
the program to exit if any of the getsym routines caused an error.  The
reason for doing things this way is to detect as many errors as possible
in one run (having the getsym routines cause the programs to bomb on
errors may mean the user has to repeatedly edit a parameter file,
discovering only one error at a time).  
.lp
Three types of errors can occur in the getsym routines:  undefined
symbol, type mismatch, or overflow (number of values given exceeds
maxval).  For all these errors, an error message is printed when 
the error is detected and calling
.i symerr_exit 
will cause program exit.  
.lp
Another useful library routine is
.i symtype
(3\-\s-1ESPS\s+1), which returns the type of a given symbol.  In
particular, it returns one of the integer symbolic constants ST_INTVAL,
ST_CHRVAL, ST_FLOVAL, ST_STRVAL, ST_FARRAY, ST_IARRAY, or ST_UNDEF
(undefined).  
.sh 2 "Writing Values to ESPS Common"
.lp
Programs can leave values in ESPS Common for use by other programs.  
To do this, they call the following "putsym" routines (which 
correspond to the "getsym" routines discussed earlier):
.nf

.TS
box,center;
c s
c | c
l | li.
Writing Value to ESPS Common
_
Type of Symbol	Program to Call
_
int	putsym_i
double	putsym_d *
char	putsym_c *
string	putsym_s
int array	putsym_ia *
double array	putsym_da *
.TE

(* = not implemented yet)
.fi
.lp
Because program communication through the Common file is not reliable 
if the programs involved are all on a series of connected pipes, 
most ESPS programs do not write the Common file if the output is 
standard output.  
.sh 2 "Example"
.lp
Here is a sketch of code used to process parameters from the parameter
and common files:
.vS
.nf

    main(argc, argv)
    int argc;
    char **argv;
    {
     .
     .
     .
    /* parse command line for parameters */
    while ((c = getopt(argc, argv, "p:")) != EOF)
	switch (c) 
        {
	    case 'p':
		prange = optarg;
		pflag++;
		break;
	    default:
		SYNTAX;
	}
     .
     .
     .
    /*process input SD file -- name is sd_file, header is ih*/
     .
     .
     .
    /*set default values for start and nan*/
    start = 1;
    nan = MAXLONG;
    /*build parameter symbol table*/
    read_params("params", SC_CHECK_FILE, sd_file);
    /* now read in the values of the parameters from the symbol table */
    /*start and nan are optional in parameter file*/
    if (sym_type("start") != ST_UNDEF) start = getsym_i("start");
    if (sym_type("nan") != ST_UNDEF) nan = getsym_i("nan");
   /*the other parameters are not optional*/
    decrem = getsym_s ("decrem");
    harmonic_mult = getsym_d ("harmonic_mult");
    symerr_exit();      /* exit if any errors occurred */
    last = start + nan - 1;
    /*command-line option might override start and last*/
    if (pflag) range_switch(prange, &start, &last, 0);
     .
     .
     .
    /*write values to ESPS Common*/
    if (strcmp(oname, "<stdout>") != 0) {
        if (putsym_s("filename", sd_file) == -1)
	    (void) fprintf (stderr, "error writing filename symbol in Common.\n");
        if (putsym_i("start", start) == -1)
	    (void) fprintf (stderr, "error writing start symbol in Common.\n");
        if (putsym_i("nan", nan) == -1)
	    (void) fprintf (stderr, "error writing nan symbol in Common.\n");
    }
    exit(0);
    }

.fi
.vE
.lp
This example includes an example of using the library routine
.i range_switch
(3\-\s-1ESPS\s+1) to aid in processing options of the form 
\fB\-p\fIstart:last\fR.  
.sh 2 "Parameter file implementation notes"
.lp
The routine
.i read_params
is implemented as a YACC grammar that calls a lexical analyzer built by
LEX.  As the input is parsed, symbol in Commons are added to a hash table.  LEX
imposes a couple of limitations on the input:  tokens (including
character strings) can be no more than 200 characters long (in the input
form, including quotes and backslashes), and there may be no null
characters (ASCII 0) in the input (LEX will interpret a null character
as end of file).  The hash table has a limited size; it is large enough
so this is not a concern.  Strings and identifier names are stored in
dynamic memory, as are arrays.  Arrays are stored internally as linked
lists, mainly because these are easier to build recursively using YACC
rules.  
.lp
The programmer should not depend on any of these characteristics of
the implementation, as all are subject to change (though I doubt we'll
scrap LEX and YACC).
.sh 1 "Possible Changes"
.lp
Included files may be added to parameter files. If nesting is allowed,
only a fairly shallow level of nesting will be permitted. One possible
syntax is a line containing only "@filename".  The format of parameter
files might also be changed to something more user-friendly.  
.sh 1 "Relation Between Parameter Names and Header Items"
.lp
If the value of a parameter affects data in output \s-1ESPS\s+1 files, then the
parameter value should be stored in the output file header. The names
of parameters should be the same as the names of header items; thus we
have parameters like "order" corresponding to the structure tag "order".
Some optional header parameters correspond to rational functions in the
Z domain; these parameters are specified as two floating array parameters,
one with the suffix "_z" (to represent the zero polynomial) and one with
the suffix "_p" (to represent the pole polynomial). Thus to specify a
filter transfer function, we might have
.(l
float filter_z = { b0, b1, b2 },
      filter_p = { a0, a1, a2, a3};
.)l
where the bn and an terms are replaced by appropriate values.
.lp
Parameters that only affect terminal or graphic output for a specific
program may have arbitrary names and are not stored in file headers; all
names must be documented along with the programs they affect.  See the 
"ESPS PARAMETERS" sections of [1, Section 1] man pages.  
.sp 3
.ce 1
(end)