files.vtme

speech signal process tools

.i genhd_list, 
or by checking for a NULL return value from 
.i get_genhd.  
.sh 1 "Data Structures"
.lp
The data structures for data records in the different types of
\s-1ESPS\s+1 files are specified in the Section 5 manual pages that
describe the file formats.  The general approach is to define a C
structure that represents one data record in the file.  Access functions
are available to support reading and writing such records, so that
programmers can deal with the C structure and ignore the issue of how
that structure is stored in the file.  
.sh 2 "Data Access Routines"
.lp
In general a function named \fIget_\fRxx\fI_rec\fR and one named 
\fIput_\fRxx\fI_rec\fR are provided to get and put records from/onto
an \s-1ESPS\s+1 file type xx.   There is also  n\fIallo_\fRxx\fI_rec\fR 
function that allocates memory for one record.  
In most cases, the size of
certain elements of the record, depend on values in the file header.
.lp
For example, here is an example of reading a \s-1SPEC\s+1 record:
.vS
.nf

    FILE *ifile;
    struct ana_data *p;
    struct header *ih;
    .
    .
    .
    ifile = fopen(in_file,"r");    	/* open the file */
    ih = read_header(ifile);		/* read the header */
    if (ih->common.type != FT_SPEC) bomb();/* must be an ANA file */
    p = allo_ana_rec(ih);		/* allocate the record */
    if (!get_ana_rec(p,ih,ifile) eof();	/* read record */
    nfreq = p->n_frqs;			/* get number of frequencies*/

.fi
.vE
.lp
The pointer p could be used in subsequent calls
to 
.i get_ana_rec
provided that the program deals with only one record at a time.  If 
more than one record is needed at the same time within the program, 
additional pointers must be declared and additional space must be
allocated by calls to 
.i allo_ana_rec.
.lp
For most of the defined file types (\s-1SD\s+1 being the only current
exception) the type of the data (\fIe.g.\fR float, integer, etc.)  is
fixed and defined by the file format itself.  The header access
routine \fIwrite_header\fR automatically sets the type fields in the
common part of the header to their correct values (which depend on
various other fields in the header).  The type codes might be set by code
like this (this is done within
.i write_header
\- most ESPS programmers will never have to do anything like this):
.vS
.nf

    struct header *h;
    {
    . . .
    /* the tag doesn't count here */
    h->common.ndouble = 0;
    h->common.nfloat = 3 * val1 + 2;
    h->common.nlong = 0;
    h->common.\fRshort = 1;
    h->common.nchar = 0;
    }
	
.fi
.vE
.lp
The actual code in the library has additional logic to insure that it is
being used properly.  
.lp
There is one case where the type code fields are not set properly by 
.i write_header
\- SD files.  Since SD files can have data records of different types
(unlike other current file types, in which the types in records are 
pre-defined), the user has specify what type of SD record is wanted.  
This is done by means of the function
.i set_sd_type,
which must be called before writing any data to the file and before 
calling 
.i write_header.  
SD files are exceptional in one other respect, namely
that the "get" and "put" routines come in several flavors.  Recognizing
that programmers will sometimes want to read or write SD records to or
from short, float, and double arrays, different routines are provided to
support these cases.  For example, the routine
.i put_sd_recf
will write SD records from a program array of type float.  Note that 
the type of SD record (i.e., the type that will be stored in the SD 
file) does not matter here.  Provided that there has been a previous
call to 
.i set_sd_type,
the right conversion will be performed on output. 
.lp
As mentioned above, FEA files provide a mechanism to define their own
record structure.  That is, users can determine the number, types,
sizes, and names of the items stored in FEA records.  FEA files include
special support for labelling the records with pointers to other source
files.  The (3\-\s-1ESPS\s+1) functions that deal with FEA files are:  \fI
allo_fea_rec, add_fea_fld, fea_decode, fea_encode, get_fea_ptr,
get_fea_rec, print_fea_rec, \fRand \fIput_fea_rec\fR.  For a detailed 
introduction to FEA files, see [5].  
.sh 2 "Using \fIeopen\fP"
.lp
Many ESPS programs go through a sequence of getting a command-line
file name, checking to see if it is a "\-" (for standard input or
output), opening the file, and checking to see that is an ESPS file 
type of the proper type (and proper subtype for FEA files).  Here's 
an example with a FEA_ANA file:
.vS
.nf

    /*
     * open the input file 
     */
    if (optind < argc) {
	in_fea = argv[optind++];
	if (strcmp (in_fea, "-") == 0)
	    in_fea = "<stdin>";
	else
	    TRYOPEN (argv[0], in_fea, "r", infea_strm);
	}
    else {
	Fprintf(stderr, "no input file specified.\n");
	SYNTAX;
        }
    /*
     * check for FEA_ANA ESPS file
     */
    if ((fea_ih = read_header(infea_strm)) == NULL)      
	ERROR_EXIT("couldn't read input FEA file header");
    if(fea_ih->common.type != FT_FEA)
	ERROR_EXIT("Input file is not a FEA file");
    if(fea_ih->hd.fea->fea_type != FEA_ANA)
	ERROR_EXIT("Input file is not FEA_ANA type");
    /*
     * allocate a record; input a record, and process
     */
    anafea_rec = allo_anafea_rec(fea_ih);
    (void) get_anafea_rec(anafea_rec, fea_ih, infea_strm);
    if (*(short *)get_genhd("spec_rep", fea_ih) != RC) 
        ERROR_EXIT("FEA_ANA file does not have reflection coefficients");
    rc0 = anafea_rec->spec_param[0];   /*get first reflection coefficient*/

.fi
.vE
.lp
Often, code like the above can be simplified by using 
.i eopen,
as follows:
.vS
.nf

    if (optind < argc) 
        in_fea = eopen(ProgName, argv[optind++], "r", FT_FEA, FEA_ANA, &fea_ih, &infea_strm);
    else {
            Fprintf(stderr, "no input file specified.\n");
            SYNTAX;
    }
    /* note that standard input is allowed, so we don't need to check in_fea
     *
     * allocate a record; input a record, and process
     */
    anafea_rec = allo_anafea_rec(fea_ih);
    (void) get_anafea_rec(anafea_rec, fea_ih, infea_strm);
    if (*(short *)get_genhd("spec_rep", fea_ih) != RC) 
        ERROR_EXIT("FEA_ANA file does not have reflection coefficients");
    rc0 = anafea_rec->spec_param[0];   /*get first reflection coefficient*/
.fi
.vE
.sh 2 "Reading Data Files with Generic Programs"
.lp
One goal of ESPS is to allow so-called "generic" (also called "dumb") 
programs to operate on
\s-1ESPS\s+1 data files.   An example of such a program is
.i stats
(1\-\s-1ESPS\s+1).  This program computes certain statistics on records
in a data file, without knowledge of the particular data structure.
Clearly, in order to support this class of programs sufficient
information must be available in the file header.  To provide that
information, the common part of the header contains the number of
doubles, floats, longs, shorts, and characters that comprise a record
within the file.  Moreover, the data in each record is stored in the
order listed \- i.e., the given number of doubles followed by the given
number of floats, etc.  These items are set automatically by 
.i write_header
when the ESPS file is created (except in the case of SD files, where
a call to 
.i set_sd_type
is also needed), and they can be used by generic programs to properly
read a record.  To simplify this further, the library function 
.i get_gen_recd
is
provided to read an arbitrary \s-1ESPS\s+1 record into an vector of
doubles.  A short example of reading records from a
data file in a non-type specific manner is:  
.vS
.nf

    FILE *ifile;
    struct header *ih;
    double tag;
    double dbuf[100];
    .
    .
    .
    ifile = fopen(in_file,"r");
    ih = read_header(ifile);
    if (get_gen_recd(dubf, &tag, ih, ifile) == EOF) done();    
    a = dbuf[2];		/* access an element */
    
.fi
.vE
Programmers and users sometimes need to know the correspondence between
this generic view of an ESPS record and the type-specific view provided
by the C structures such as this one for PIT files (see 
.i PIT
(5\-\s-1ESPS\s+1)):
.vS
.nf

    struct pitch {
    	long tag;		/*position in the reference file*/
    	float pulse_dist;	/*pulse to pulse distance*/
    	float raw_pulse_dist;	/*raw pulse distance*/
    }

.fi
.vE
.lp
For example, a user of a generic statistics program might want to get
statistics on the pulse_dist component of pitch records, and to do so
must be able to state which element of the record this is from the
viewpoint of generic programs.  This information is provided in 
the section "RECORD ELEMENT FILE STRUCTURE" within each Section 5 ESPS
manual page.  Thus, for example, by reading 
.i SCBK
(5-\s-1ESPS\s+1) you can determine that the final_dist component 
of SCBK records is the element number 1 from the generic viewpoint.  
In the case of FEA files, the correspondence between the FEA-specific
view and the generic view is more complicated since a single such 
table will not suffice, and for this reason an ESPS program is
provided to translate between the two views; see \fIelemfea\fR
(1\-\s-1ESPS\s+1).  

.sp 2
.ce 1
(end)