param.doc

speech signal process tools

       Parameter processing takes place in two steps: building a symbol table
       from  the  parameter  and  common  files, and reading values from that
       table.

       7 .1 .  Building the Symbol Table

       The program read_params (3-ESPS) is called to  process  the  parameter
       and  common  files  and  to  build an internal symbol table from which
       parameter values can be retrieved. 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) (Sec-
       tion 2.1) is to be enforced.  For example, the call


       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                page 13


           /*sd file is the name of an input SD file*/
           (voi-) read params("params", SC CHECK FILE, sd file);
                      -                   -     -        -
       specifies that the parameter file is "params" (the ESPS  default  con-
       vention),  and  that  the ESPS common file is to be processed provided
       that its  "filename"  entry  matches  the  contents  of  the  variable
       "sd_file".   Similarly,

           (void) read params("params", SC CHECK FILE, NULL);
                      -                   -     -
       processes the parameter file and the common file without regard to any
       "filename" entry in the common file.

       Read_params detects following types of errors:

           It was asked to read a parameter file but couldn't (returns -1)
           It was asked to read common but couldn't (returns -2)
           It was asked to read both parameter and common files but couldn't (returns -3)
           File contains syntax errors
           Symbols multiply defined
           Type conflicts

       If the parameter and possibly the common file are opened successfully,
       read_params  attempts  to  process  them  entirely  even if errors are
       encountered, printing appropriate messages on the standard error  out-
       put.   Each  syntax  error message indicates the line of the parameter
       file where it occurred.  However, a program exit will occur after pro-
       cessing  is complete if any errors were present in the file.  The rou-
       tine either returns successfully, in which  case  a  symbol  table  is
       built, or the program exits.

       7 .2 .  Reading Parameter Values

       Once the internal symbol table has been built by calling  read_params,
       programs  can  retrieve  the values of specific symbols by calling the
       various "getsym" library routines noted in the following table:


                       _____________________________________
                       |_____Reading_Parameter_Values_______|
                       | Type of Symbol   | Program to Call |
                       |__________________|_________________|
                       |int               | getsym_i        |
                       |double (or float) | getsym_d        |
                       |char              | getsym_c        |
                       |string            | getsym_s        |
                       |int array         | getsym_ia       |
                       |double_array______|_getsym_da_______|



       As described earlier, if the parameter file indicates that the  symbol
       is indefinite, the user is prompted for a value.  The default value is


       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                page 14


       used if the user types a RETURN in response to the prompt.

       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  sym-
       bol  table  module  keeps  track  of  errors;  the routine symerr_exit
       (3-ESPS), 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 possi-
       ble  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).

       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 symerr_exit will cause program exit.

       Another useful library routine is symtype (3-ESPS), 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).

       7 .3 .  Writing Values to ESPS Common

       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):


                       _____________________________________
                       |___Writing_Value_to_ESPS_Common_____|
                       | Type of Symbol   | Program to Call |
                       |__________________|_________________|
                       |int               | putsym_i        |
                       |double (or float) | putsym_f        |
                       |char              | putsym_c *      |
                       |string            | putsym_s        |
                       |int array         | putsym_ia *     |
                       |double_array______|_putsym_da_*_____|


       (* = not implemented yet)

       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.

       7 .4 .  Standard I/O

       Programs should not read common if the input file is  standard  input.
       Programs  should  not  write  common  when  an output file is standard


       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                page 15


       output. These rules are to prevent confusion from  arising  when  pro-
       grams are used in pipes.

       7 .5 .  Example

       Here is a sketch of code used to process parameters from the parameter
       and common files:

           main(argc, argv)
           int argc;
           char **argv;
           char *paramfile = "params";
           {
            .
            .
            .
           /* parse command line for parameters */
           while ((c = getopt(argc, argv, "p:P:")) != EOF)
                  switch (c)
               {
                      case 'p':
                            prange = optarg;
                            pflag++;
                            break;
                      case 'P':
                            prange = optarg;
                            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*/
           (void) read params(paramfile, SC CHECK FILE, sd file);
           /* now read-in the values of the-param-ters fro- the symbol table */
           /*start and nan are optional in parameter file*/
           if (symtype("start") != ST UNDEF) start = getsym i("start");
           if (symtype("nan") != ST U-DEF) nan = getsym i("-an");
          /*the other parameters ar- not optional*/    -
           decrem = getsym s ("decrem");
           harmonic mult =-getsym d ("harmonic mult");
           symerr e-it();      /*-exit if any -rrors occurred */
           last =-start + nan - 1;




       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                page 16


           /*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)
                      (vo-d) fprintf (stde-r, "error writing filename symbol in Common.\n");
               if (putsym i("start", start) == -1)
                      (vo-d) fprintf (stderr, "error writing start symbol in Common.\n");
               if (putsym i("nan", nan) == -1)
                      (vo-d) fprintf (stderr, "error writing nan symbol in Common.\n");
           }
           exit(0);
           }


       This  example  includes  an  example  of  using  the  library  routine
       range_switch  (3-ESPS)  to  aid  in  processing  options  of  the form
       -pstart:last.

       7 .6 .  Advanced Parameter Processing

       As shown in the example above, most programs can do what's needed with
       a combination of the functions read_params, symtype, getsym_X, putsym,
       and symerr_exit.  This is usually the  case  if  the  input  parameter
       names  are known in advance and if no use will be made of the optional
       parameter limits.  In the more general case,  however,  the  functions
       symlist,  symdefinite,  symchoices,  symrange, symprompt, getsymdef_X,
       and fputsym_X may be needed (see the one-line descriptions in  Section
       2).

       8 .  Parameter Processing from Shell Scripts

       As is typically the case with UNIX-based applications, one  can  write
       an  ESPS  shell  script with the same user-interface as an ESPS C pro-
       gram.  In the case of parameter processing, this means  that  a  shell
       script  must  be  able to process the standard -P option (specifying a
       parameter file).  The program getparam makes this easy; it processes a
       named  parameter  file  and Common and returns (in ASCII) the value of
       any named parameter.

       9 .  Parameter file implementation notes

       The routine read_params is implemented as a YACC grammar that calls  a
       lexical  analyzer  built  by  LEX.  As the input is parsed, symbols in
       ESPS Common are added to a hash table.  LEX imposes a couple of  limi-
       tations  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.


       Version 3.5                      ERL                           1/22/93







       ETM-S-86-12:jtb                                                page 17


       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.

       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).

       10 .  Possible Changes

       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.

       11 .  Relation Between Parameter Names and Header Items

       If the value of a parameter affects data in output  ESPS  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

           float filter_z = { b0, b1, b2 },
                 filter_p = { a0, a1, a2, a3};

       where the bn and an terms are replaced by appropriate values.

       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.



                                       (end)















       Version 3.5                      ERL                           1/22/93