files.vtme

speech signal process tools

    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
In the case of the built in file types, 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
\- old style 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.  The new FEA_SD file
type, which is intended to replace SD files, also allows separate
specification of the data type stored in the file and the data type in
memory (see \fIinit_feasd_hd\fP and \fIallo_feasd_recs\fP).  
.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
Before FEA files were introduced, a different mechanism was available
to allow so-called "generic" (also called "dumb") programs to operate
on \s-1ESPS\s+1 data files without knowing the details of the file
format.  We shall describe that mechanism here, but users should avoid
using it as it will be phased out in later releases. 
.lp
An example of such a "dumb" generic 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).  
.sh 1 "The Preamble - Reading ESPS Files with non-ESPS Programs"
.lp
Each ESPS header contains a fixed size structure which we call the
preamble.   The preamble contains information necessary for the
operation of the \fIread_header\fR function and will not be described in
detail here.   However, the preamble does contain information that
allows a non-ESPS program to skip over an ESPS header to access the data
directly.   Note that this can also be achieved by the user level
program \fIbhd\fR.   The assumption here, is that the user needs to
incorporate into an existing non-ESPS program to ability to read an ESPS
file.
.lp
From the view point of a non-ESPS program, the preamble is the first 8
long words (32 bytes) of the file.   The preamble is always written in
the Entropic EDR format (see reference [8]), so on a machine with a
different default byte order the user program will have to byte swap the
data.  EDR format has the same byte order as Sun workstations, so if
your machine's order if different, you will have to convert it.
.lp
This is the preamble:
.vS
.nf
struct preamble {
   long         machine_code;	/* machine which wrote file, see header.h */
   long         check_code;	/* version check code */
   long         data_offset;	/* data offset (in bytes, from 0) in file */
   long         record_size;	/* record size in bytes */
   long         check;		/* ESPS magic number, same as main header */
   long         edr;		/* YES if EDR_ESPS, NO if native */
   long         align_pad_size;	/* alignment pad need for some SD files */
   long         foreign_hd;	/* pointer to foreign header, -1 if */
				/* there is none */
};
.fi
.vE
.lp
The third long word contains the offset from the beginning of the file
to the first data record (in bytes).   So to skip over the ESPS header,
simply seek to this location in the file.   The next long word, contains
the record size in bytes.   For a better detailing of the record format
use the program \fIfea_element\fR(1\-ESPS) or \fIgen_element\fR(1\-ESPS).
.lp
All a non-ESPS need do to read an ESPS file, is to declare this
structure, read in the first part of the file into it and then seek into
the file to the point indicated by \fIdata_offset\fR.   If the machine
on which you are reading this file has a different byte order from EDR,
the you will have to byte swap these fields after reading them.   The
field \fIedr\fR in the preamble tells you whether you have to worry
about the data format of the data records, with respect to byte order
and floating point format.   If \fIedr\fR is 1, then the data is in EDR
format.  This is the most common data format in the workstation market.
If your machine's data formats are different than that of a Sun, then
you will have to convert the data.   If the \fIedr\fR flag is 0, then
the file is in the native format of the machine which wrote it.  You
will have to determine that machine type (look at \fImachine_code\fR)
and convert from that format to that of the destination machine.   In
most cases there is nothing to do, but some cases can be difficult.  It
is possible that you can ensure that the ESPS file is written in the
easiest format for you to deal with by your non-ESPS program.  See
reference [8] for details on this.
.lp
If \fIforeign_hd\fR in the preamble is not -1, then the file contains a
foreign header and this is a pointer to it.   Please note that this is
not the normal way for ESPS programs to access the foreign header.  That
would be via the generic item \fIforeign_hd_ptr\fR and
\fIforeign_hd_length\fR.   The foreign header pointer in the preamble
is provided just for the case of non-ESPS program access.

.sp 2
.ce 1
(end)