param.vtme

speech signal process tools

.\" for SPS.   
.lo
.de SM          \"macro to shrink left margin
.br
.nr $i \\n($i+\\$1i
..
.de RM          \"macro to restore original left margin
.br
.nr $i 0
..
.SJ "Parameter and Common Files in ESPS"
.AU "Joe Buck"
.RB "John Shore"
.TM ETM-S-86-12:jtb 1.3 6/5/87
.*R
Entropic Signal Processing System (ESPS), Programmers Reference Manual
.*R
ETM-S-86-13:rap, Data Files in the Entropic Signal Processing System (ESPS)
.*R
ETM-S-86-25, Guidelines for Implementing ESPS Feature File Subtypes
.*R
J.  Shore and R.  Parker, Introduction to the Entropic Signal Processing System (ESPS)
.*R
ETM-S-86-14, Entropic Signal Processing System Programming Guidelines
.sh 1 Introduction
.lp
This document describes the Entropic Signal Processing System (\s-1ESPS\s+1)
parameter and common files, and presents information required to write
programs using them.  
.(f
\(co Copyright 1987 Entropic Speech, Inc.; All rights reserved.  
.)f
.lp
The reader must also read and understand the \s-1ESPS\s+1 manual pages
in reference [1].   These manual pages are in the standard \s-1UNIX\s+1
format; section 1 describes user commands, section 3 describes library
routines, and section 5 describes the format of \s-1ESPS\s+1 files (see 
also [2] and [3]).
.lp
For a general introduction to ESPS, see [4].  
.sh 1 "ESPS Parameter and Common Files"
.lp
Many ESPS programs are affected by a large set of parameters.  Because 
it would be extremely inconvenient to type their values as command line 
options each time a program is called, ESPS uses a different approach.  
ESPS programs get their parameters from three sources:
.SM .5i
.ip \(bu 3
the ESPS parameter file
.ip \(bu 3
the ESPS common file
.ip \(bu 3
command line options
.RM
.lp
In general, if a command-line option is available to set a parameter
value, its use overides any of the other mechanisms by which programs
get parameter values.  
.sh 2 "Parameter and Common File Processing"
.lp
For parameters that are not specified on the command line (either
because no option is available or because an available option is not
used), the parameters usually are obtained from an ESPS parameter file,
which specifies parameter values with a C-like syntax.  
.lp
Sometimes, a value in the parameter file is superceded by a value in the
ESPS common file \- this is determined by the following rules.  For some
programs, the parameter file value is superceded if rules (1)-(3) apply; 
for other programs, it is superceded if rules (1)-(4) apply.  
.SM .5i
.ip (1)
Common file processing has not been disabled.
.ip (2)
The common file exists and is younger than the parameter file. 
.ip (3)
The common file contains a value for the parameter in question.  
.ip (4)
A file name stored in the common file matches a stated file name.  
.RM
.lp
The purpose of the ESPS common file is to allow one ESPS program to
communicate parameter values to another ESPS program that is run 
subsequently.  For example, suppose that
.i plotsd
(1-ESPS) is used to plot the first 10,000 points of an SD file in a
Masscomp graphics window: 
.nf
 
	%plotsdm -p1:10000 file.sd
 
.fi
After this plot is made, the user can run
.i range
(1-ESPS) to select a portion of the displayed data.  When 
.i range
exits, it writes the selected range and the filename "file.sd" into the
ESPS common file.  If the user then runs 
.nf
 
	%plotsdm
	%play

.fi
(i.e., without any command line options), the selected range of the same
file will be displayed and then played.  
.lp
For most ESPS programs, common file processing is enabled (i.e.,
parameter file values will be superceded if rules (2)-(3) or (2)-(4)
above apply).  Rule (4) was introduced to make it easier for ESPS
programs to do what users expect \- often, it would be annoying or a
mistake to use values from ESPS common unless one is processing the same
file that was being processed when ESPS common was written.  Which set of
rules applies can be determined from the "ESPS COMMON" section of the man
pages.  Before running an ESPS program, a user can always have the effect
of disabling common file processing by removing the common file or
touching the parameter file.  Some programs may also have an option to
disable common file processing.  Also, the user can disable common 
file processing completely (see next subsection).  
.lp
For details about the format and processing of parameter files, 
see [4].  
.sh 2 "Parameter and Common File Names"
.lp
The default convention for the parameter file name is "params" in the
current directory, but for most programs this can be changed by a
command line option (usually \fB\-P\fP).  The default ESPS common file is
".spscom" in the user's home directory, but this can be reset by using
the SPSCOM \s-1UNIX\s+1 environment variable, e.g.:  
.nf

	%setenv SPSCOM /u/shore/anacommon

.fi
.lp
Common file processing can in effect be disabled by the following command:
.nf

	%setenv SPSCOM /dev/null

.fi
.sh 1 "Format of Parameter and Common Files"
.lp
Parameter files and common files are written in
a C-like language. Parameters may have six types: integer, real (stored
as double precision values), string, character, array of integer, and
array of real. 
.lp
The  assignment of a value to a symbol may be definite or indefinite.
If it is indefinite (indicated by the assignment operator "?=" or "=?")
then the user will be prompted for the value to be used. If the user
enters a RETURN in answer to the prompt, the default value will be
used.
.lp
A simplified grammar follows. In this grammar, parentheses indicate that the
contents may be repeated zero or more times. Square brackets indicate that
the contents are optional (zero or one repetitions). Vertical bars indicate
"or". CHRVAL, STRVAL, FLOVAL, and INTVAL represent legal C tokens for
characters, strings, real values, and integers respectively. IDENT
represents any legal C variable name, other than one of the reserved
keywords. Case is significant, and all characters of names are significant
(the restriction imposed by LEX, which builds the lexical analyzer, is about
200 characters). Most C escape sequences like '\en' are supported in
character and string constants. Character constants like '^b', meaning
control-b, are also supported. However, octal and hexadecimal numbers are
not supported. Multiline strings are not supported.
.(l
file :==  ( statement )
statement :== type decl ( ',' decl ) ';'
type :== "int" | "float" | "char" | "string" | "char" '*'
decl :== IDENT assop value [prompt]
value :== CHRVAL | STRVAL | FLOVAL | INTVAL | array
array :== '{' num ( ',' num ) '}'
num :== INTVAL | FLOVAL
prompt :== ':' STRVAL
assop :== '=' | '=' '?' | '?' '='
.)l
The following keywords are reserved: int, char, string, float,
yes, no, true, false. The keywords "yes" and "true" are treated
as integer constants with value one (the C convention for expressing
logical true); the keywords "no" and "false" are integer constants
with value zero.
.lp
The comment convention is different from C. It is the same as for the
C shell. A '#' character indicates that the rest of the line is a
comment, unless it is contained in a character or string constant.
This makes it easier to comment out lines.
.lp
Here is an example of a parameter file:
.(l
int order ?= 10 : "Model order";	# ask for prompt
int verbose = no;
#preemphasis specification
int preflg = yes;
float	pre_num = { 0.9, -0.5 },   # zeros of preemph filter
	pre_den = { 0.99, -0.99 }, # poles of preemph filter
	scale = 0.25;
int frmlen ?= 150: "Length of analysis window";
int nshft ?= 180: "Distance between frames";
#method for autocorrelation computation
string method = "BURG"; #Burg method
.)l
.sh 2 "Parameter Assignment Statements"
.lp
There are three types of assignment statements.
The most basic statement is something like
.(l
int M = 22;
.)l
In this type of statement, a symbol named
M is created, assigned
the type integer and the value 22. If the name has been declared
previously, an error occurs. Type conversions, where sensible, work.
An integer or character value may be assigned to a floating variable,
and a character may be assigned to an integer variable. Integers
in the range 0:127 may be assigned to character variables. Arrays
may mix integers and floating values, provided that the array is
assigned to a floating variable. Some things that don't work:
.(l
int n = 12.0; # can't assign float to int
char q = "a"; # can't assign string (even 1 char) to char
string a = 'c'; # can't assign character to string
char a = 'b', *c = "def"; # unlike C, "char *" is just
			  # a synonym for "string";
			  # no mixing allowed
.)l
The other two types of assignment statements attach a default value
to a variable and are indicated by adding a question mark to the
equal sign (either before or after). An optional prompt string may
appear, separated by a colon from the declaration.
.(l
int M ?= 22;
int M ?= 22 : "Model order";
.)l
When an attempt is made to retrieve the value of M,
the user is
prompted. If no prompt string is given, the variable name is used
as the prompt.
The default value is placed in square brackets:
.(l
M [22]:
Model order [22]:
.)l
.sh 1 "Programming Procedures for Parameter and Common Files"
.lp
Parameter processing takes place in two steps: building a symbol
table from the parameter and common files, and reading values from 
that table.  
.sh 2 "Building the Symbol Table"
.lp
The program
.i read_params
(3\-\s-1ESPS\s+1)
is called to process the parameter and common files and to build an