guide.vme

speech signal process tools

	ESPS COMMON
	ESPS HEADERS
	FUTURE CHANGES

.fi
The "ESPS PARAMETERS" section lists the parameters that are read from the
parameter or common file and gives their types.  The section should
explain how the program uses each of these parameters.  
.lp
The "ESPS COMMON" section describes how the ESPS Common file is
processed (e.g., whether the \fIfilename\fP in Common is required to
match a particluar file name), and what items, if any, are written to
the Common file.  
.lp
The "ESPS HEADERS" section lists which header items are read by the 
program (including generic header items), and explains how the program
depends on them.  This section also lists the header items that 
written by the program.  
.lp
The "FUTURE CHANGES" section is intended to record ideas for enhancing
the program.  This section should be included even when the manual 
page is written before the program, since its contents may affect 
the program structure.  
.sh 1 "Command Line Format and Pipelines"
.lp
The command line for any ESPS program will be
.(l
\fIprog options input-files output-files
.)l
Options, if present, will be of the standard
\s-1UNIX\s+1 form (
.b \-x
,
.b \-x
\fI\ text,\fR or 
.b \-x
\fItext\fR).
.lp
By default, the parameter file for the program will be the file "params"
in the current directory.  All ESPS programs that process parameters will
recognize the option 
.(l
\fB\-P \fIparamfile\fR
.)l
which will specify an alternative parameter file name.
.lp
If the output of the program is ASCII text then the default output is
standard output.   This can be redirected by the user, if desired, by
using the standard \s-1UNIX\s+1 shell facilities.    If the output of the
program is binary data, then an output file must be specified.
If a minus sign is given, then standard output is
used.  The intent here is to reduce the chance that a
user will accidently send binary data to his terminal.
Any source file name may be replaced by a minus sign, meaning that this
source is read from the standard input (if a program takes multiple source
files, only one may be read from standard input, however). 
Standard input or standard output are never to be the default if
a binary data file is involved.
.lp
Where reasonable, pipelines should be allowed.  If a program performs
random I/O on its input, that fact should be included in the user
documentation. If a program reads from a pipe, it writes the string
"<stdin>" as the source file name in the output header.  Note that 
programs that read SPS files from pipes can not depend on the header
item common.ndrec -- see ESPS(5\-\s-1ESPS\s+1).  
.lp
Programs that perform plots or dumps, or that compute statistics, have
different syntax. For one thing, they do not accept parameter files. They
are invoked by lines of the form
.(l
\fIprog options src1 [src2 ...]\fR
.)l
The output should go to the standard output.  Where reasonable, the
default behavior should be to plot on the user's screen.  Also,
device-specific output should be specifiable with the \fB\-T\fR
switch on the command line.  Where possible, values for the \fB\-T\fR
option will agree with those of the \s-1UNIX\s+1 \fIplot(1)\fR.  
Common ESPS supported options here are \fBgps, mcd, tek, \fP and
\fBimagen\fP.  
command where possible.
.sh 1 "Standard Option Letters"
.lp
When appropriate, ESPS programs should use the the following standard
options:
.nf
.ta .5i

	\fB\-c\fP = comment
	\fB\-e\fP = elements
	\fB\-f\fP = fieldname 
	\fB\-g\fP = gain
	\fB\-h\fP = history file
	\fB\-k\fP = clock, keyword
	\fB\-m\fP = mode, method
	\fB\-n\fP = number, value
	\fB\-p\fP = points 
	\fB\-P\fP = parameter files/values
	\fB\-r\fP = records
	\fB\-s\fP = seconds
	\fB\-t\fP = text, title
	\fB\-T\fP = device type
	\fB\-u\fP = unvoiced speech
	\fB\-v\fP = voiced speech/records
	\fB\-w\fP = width, window
	\fB\-x\fP = debug level 
	\fB\-X\fP = x-axis
	\fB\-y\fP = y-axis 
	\fB\-Y\fP = y-axis
	\fB\-z\fP = suppress 
	\fB\-Z\fP = suppress

.ta
.fi
.sh 1 "Command Line Options and Parameter File Values"
.lp
In general analysis conditions are specified in a file read by the
ESPS program (see reference (2) for details of the parameter file).
However, if the programmer decides that certain parameter values will
change often from run to run, then these values can be specified on
the command line as options.  When used, command line values will
override values in the parameter file given for the variable.
Analysis parameter values should be stored in the output file header,
using either built-in header fields or generics; this holds whether the 
parameters were specified on the command line or in the parameter file.
.lp
For programs that process parameter and common files, the manual 
page must include the sections "ESPS PARAMETERS" and "ESPS COMMON".  
The first of these should document all of the parameters that are 
read from the parameter file.  The second should explain how ESPS common
is handled by the program (ignored, processed, or processed with 
a filename restriction -- see [3]), and it should document any 
values that are written to ESPS common.  
.lp
In order to allow new analysis condition options to be added for
testing or experiments, without modifying the data file headers
immediately, but still record all analysis conditions in the output
file header, all ESPS programs will store the command line that invoked
them in the comment field of the of the output file header.
A library function, 
.i get_cmd_line
(3\-\s-1ESPS\s+1)
returns the command line as a string for inclusion in the header.
.sh 1 "Internal Structure of ESPS Programs"
.lp
All ESPS programs go through similar steps at the beginning and at the
end.  First, the options, if any, are parsed using the \fIgetopt(3)\fR
subroutine (note:  \fIgetopt\fR is standard in System V.  We have a
public-domain version in the ESPS library).  Source file headers are read
using the \fIread_header\fR(3\-\s-1ESPS\s+1) routine and the various generic header
access routines:
.i genhd_list
(3\-\s-1ESPS\s+1), 
.i genhd_type
(3\-\s-1ESPS\s+1), and
.i get_genhd
(3\-\s-1ESPS\s+1).  The routine \fIeopen\fP(3\-\s-1ESPS\s+1) can be
used to facilitate file opening, header reading, and file type
checking.  Then \fIread_params\fR(3\-\s-1ESPS\s+1) is called to read
the parameter and common files and create a symbol table; needed
parameters are checked and retrieved from the symbol table using the
symbol table access routines (\fIgetsym_X\fR(3\-\s-1ESPS\s+1)).  The
routine \fIsymerr_exit\fR(3\-\s-1ESPS\s+1) is called after all
parameter values are retrieved; it cleans up and exits after any
symbol table errors.  Parameter values and header values are checked
for consistency (documentation for individual programs will describe
the checks performed), and the program exits if the source file(s)
are the wrong type or are inconsistent with one another.  
Record keeping is performed using
.i add_source_file,
.i get_cmd_line,
and 
.i add_comment
(3\-\s-1ESPS\s+1). (See the discussion about the order of using
these functions in [1].)
.lp
Output headers are created with
.i new_header
(3\-\s-1ESPS\s+1), 
.i copy_header
(3\-\s-1ESPS\s+1), and the generic header routines
\fIadd_genhd\fR_X(3\-\s-1ESPS\s+1).  In most cases, all fields of the
output file header will be known before any processing is performed.
If so, the output header(s) is(are) written by calling
\fIwrite_header\fR(3\-\s-1ESPS\s+1) and any data to be written by the
program is appended.  If this is not possible, output is directed to
a temporary file, then the header is written, and then the temporary
file is dumped to the output and deleted.  This method is preferred
to patching up header locations by doing disk seeks since it allows
the output to be a pipe.  Definition of FEA file records using
.i add_fea_fld
(3\-\s-1ESPS\s+1)
must also take place before the header is written.  
.lp
All programs return zero exit status if the program's operation was
successful, and nonzero exit status if an error occurred, so shell scripts
are notified of the error condition.
.sh 1 "Compile-time vs. Run-time Symbols"
.lp
Many analysis conditions are given as character strings for names of
methods, such as AUTO_SAM, HAMMING, LPC10, etc.    These strings are
associated with C compile-time \fB#define\fR values.  For example, in
.i <header.h>
there is the statement
.vS
.nf

    #define HAMMING 1

.fi
.vE
The value that actually gets stored to identify the method in this
case is 1, but the programs all reference that value as HAMMING.
There is no built-in connection between the run-time reading of the
parameter file and the compile-time symbol HAMMING.  Of course, we
don't want to read the integer 1 from the parameter file (or command
line) in this case, and we don't want to see it in listings from
\fIpsps\fP(1\-\s-1ESPS\s+1).  To make the connection between the compile-time symbols
and the run-time reading of the parameter file, there are arrays that
contain these symbols.  A function,
.i lin_search
(3\-\s-1ESPS\s+1), searches these arrays and returns the index if the symbol
is found.  By using these arrays and this function, the programmer
can easily read character strings from the parameter file or the
command line and get the value associated with that string for
comparison against the compile-time symbols.  See
.i lin_search
(3\-\s-1ESPS\s+1) and
.i lin_search2
(3\-\s-1ESPS\s+1) for details.
.lp
These arrays can also be used to return the string associated with a
particular compile-time symbol.  For example:
.(l
printf("Method is %s\n",method_array[method_code]);
.)l
will print the symbol associated with the current value of 
.i method_code.
Many of these arrays are stored in 
.i <header.h>
for the appropriate arrays.  Others can be found by reading the
relevant program documentation.  
.sh 1 "ESPS Include Files and Library Functions"
.lp
Include files for ESPS programs are stored in a directory 
.i esps
under a location specified at install time; the suggested default is
.i /usr/esps/include.  
Programs include such files them by means of a line of the form
.vS
.nf

     #include <esps/file.h>

.fi
.vE
The install script makes sure that ESPS compilations are done with
the appropriate \fB\-I\fP flag to cause the ESPS include directory to 
be searched before the standard locations.  Here are some of the
most important ESPS include files
Currently, the following include files exist:
.ip anafea.h 10
Includes declarations needed for FEA_ANA files;
.ip header. 10
Includes declarations for header structure, header access routines
and the character arrays containing 
.i methods
and
.i codes
values for use with 
.i lin_search. 
This file is included automatically by <esps.h>.  
.ip param.h 10
Includes declarations for parameter file access routines.
This file is included automatically by <esps.h>.  
.ip ftypes.h 10
Includes declarations for file type constants.
This file is included automatically by <esps.h>.  
.ip esps.h 10
Includes some useful macro definitions and includes header.h, param.h,
and ftypes.h.   All ESPS programs should include this file, and not
make specific reference to the above three files.
.ip constants.h 10
Includes some useful constant declarations.
.ip sd.h 10
Includes declarations for SD files.
.ip spec.h 10
Includes declarations for SPEC files.
.ip filt.h 10
Includes declarations for FILT files.
.ip scbk.h 10
Includes declarations for SCBK files.  
.ip fea.h 10
Includes declarations for FEA files.  
.ip complex.h 10
Includes a typedef and useful macros for processing complex numbers
\- see 
.i complex
(3\-\s-1ESPS\s+1).  
.ip vq.h 10
Includes declarations for FEA_VQ files.  
.ip fstat.h 10
Includes declarations for FEA_STAT files.  
.lp
In most cases, an ESPS program will include \fI<esps/esps.h>\fR and one
or more type specific include files, depending on the type of data
files the program handles.  See the Section 5 manual pages [4].  
.lp
ESPS library routines are compiled into two library modules, one 
each for the general and local sections.  The default names and locations for
these are /usr/lib/libspsg.a and /usr/lib/libspsl.a.  If routines
from these are used one or the other or both switches
.i -lspsg
and
.i -lspsl
should be added on the
.i cc
command line.  If the library is stored in a different location, then 
an appropriate command line option must be used (for distributed ESPS
programs, this is handled automatically by the install script).  
.sh 1 "Defined Constants for Numerical Limits"