guide.vme

speech signal process tools

.lp
ESPS programs sometimes need to be written in terms of the 
limits on the values representable in various C numeric data types.
A set of defined constants giving the maximum and minimum 
values for various data types is available and should be 
used when appropriate.  Here are the names of the defined 
constants and their values:
.nf
.ta .5i 2i

	CHAR_MAX	127
	CHAR_MIN	-128
	SHRT_MAX	32767
	SHRT_MIN	-32768
	LONG_MAX	2147483647
	LONG_MIN	-2147483648
	FLT_MAX	(float)	3.40282346638528860e+38
	DBL_MAX		1.79769313486231470e+308

.fi
.lp
These are available in programs that contain the line
.vS
.nf

    #include <esps/limits.h>

.vE
.fi
and since that line is in the ESPS include file esps.h,
the constants are also automatically available in programs that contain
.vS
.nf

    #include <esps/esps.h>

.vE
.fi
Instead of containing private definitions like
.vS
.nf

    #define MAX_FLOAT 1.0e37

.vE
or
.vS

    #define REALLY_BIG_NUMBER 1.0e30

.vE
.fi
ESPS programs should simply refer to an appropriate constant, such as
FLT_MAX, from the list above.  They should also avoid referring to
similar definitions in the system include file /usr/include/values.h;
on Masscomp systems, for example, some of the values in values.h
cannot be processed correctly by the C compiler.  
.lp
The following names are reserved for future expansion of
esps/limits.h:  INT_MIN, INT_MAX, FLT_EPSILON, DBL_EPSILON, FLT_MIN,
DBL_MIN.  (FLT_EPSILON is intended to be the smallest positive
\fIx\fP of type \fIfloat\fP such that 1.0 + \fIx\fP != 1.0.  FLT_MIN
is intended to be the minimum positive value of type \fIfloat\fP \- a
small positive number, not a big negative number.  DBL_EPSILON and
DBL_MIN are the analogous quantities for type \fIdouble\fP.)  These
names, and the ones already defined in esps/limits.h, are taken from
a draft of the forthcoming ANSI C standard.  Under an ANSI
implementation all these constants and a number of others could be
made available by making esps/limits.h a two-line file containing
.nf

    \fB#include\fP <limits.h>
    \fB#include\fP <float.h>

.fi
.lp
The esps/limits.h file is relatively new, so some older ESPS programs
may not use these definitions.  New programs, however, should always
use them.  
.sh 1 "ESPS File Types"
.lp
For each type of file in ESPS, a symbol is defined in the file
.i ftypes.h ,
as described above.
These symbols all begin with FT_ ;
for example,
sampled data files have the type FT_SD
stored in the header type
field. The type only refers to the form of the data in the file, not its
source.  FEA file (type FT_FEA) also have subtype codes, such as
FEA_ANA and FEA_VQ.  
.sh 1 "General vs. Type Specific I/O"
.lp
For each of the defined data file types, there is a set of data access
functions (see reference (4)).  For example for SPEC files, one can use
.i allo_spec_rec
to allocate memory for a SPEC record (the size of the record depends
on values in the data file header),
.i get_spec_rec
(3\-\s-1ESPS\s+1)to read a SPEC record from a file into the SPEC record structure, and
.i put_spec_rec 
(3\-\s-1ESPS\s+1)to write a SPEC data structure onto a file.   
.lp
To support non-type specific data file input, the function
.i get_gen_recd
(3\-\s-1ESPS\s+1)reads the next record from an ESPS data file into a vector.   This
routine does not have knowledge of the data structure format for the
particular type of file being read.    Programs that use this form of
data file access, rather than the type specific form, are called
.i generic
ESPS programs.  An example of a generic ESPS program is
.i stats
(1\-\s-1ESPS\s+1).
.sh 1 "Example"
.lp
Here is a sketch of an ESPS program (this does 
.i not
correspond exactly to the ESPS program
\fIfft\fP(1\-\s-1ESPS\s+1)):
.vS
.nf

    /*
     * system include files
     */
    #include <stdio.h>
    /*
     * include files
     */
    #include <esps/esps.h>
    #include <esps/sd.h>
    #include <esps/spec.h>
    /*
     *defines
     */
    #define DFTMAX 16384
    #define Fprintf (void)fprintf
    #define SYNTAX USAGE("fft [-p range][-x debug_level] [-r nframes] file.sd file.spec")
    /*
     * external functions
     */
     . . .
    /*
     * main program
     */
    main(argc, argv)
    int  argc;
    char **argv;
    {
        char *ProgName = "fft";
        char *Version = "1.1";
        char *Date = "7/25/86";
        FILE *ifile = stdin, *ofile = stdout    /* input and output file streams */
        struct header *ih, *oh		/* input and output file headers */
        char *iname, *oname		/* input and output file names */
        struct spec_data *spec_rec	/* record for spectral data */
        char    *prange = NULL;		/* string for range specification (-p) */
        int     p_flag = 0;		/* flag for range option */
        long    nframes = 1;		/*number fixed length frames to process*/
        float   x[DFTMAX], y[DFTMAX];	/* arrays for data and fft of data */
        int     more = 1;		/* flag to indicate more sampled data*/
        . . . 
        /*
         * process command line options
         */
        while ((ch = getopt(argc, argv, "o:p:x:r:")) != EOF)
            switch (ch) {
                case 'o':
                    order = atoi(optarg);
                    break;
                case 'p': 
                    prange = optarg;
                    p_flag++;
                    break;
                case 'x': 
                    debug_level = atoi(optarg);
                    break;
                case 'r':
                    nframes = atoi(optarg);
                    if (nframes == 0) nframes = LONG_MAX;
                    break;
                default: 
                    SYNTAX;
                    break;
            }
        /*
         * open input SD file 
         */
        if (optind < argc) 
            iname = eopen(ProgName, argv[optind++], "r", FT_SD, NONE, &ih, &ifile);
        else {
            Fprintf(stderr, "%s: no input SD file specified.\n", ProgName);
            SYNTAX;
        }
        /*
        * open output SPEC file
        */
        if optind < argc) 
            oname = eopen(ProgName, argv[optind++], "w", NONE, NONE, &oh, &ofile);
        else {
            Fprintf(stderr, "%s: no output file specified.\n", ProgName);
            SYNTAX;
        }
    /*
     * read range from SPS common, if range option not used; 
     * the filename in common must match that of the input SD file
     */
        if (!p_flag) read_params((char *)NULL, SC_CHECK_FILE, iname);
        get_range(&first, &last, prange, p_flag);
        symerr_exit();  /*exit if any of the parameters were missing*/
        . . .
        nan = last - first + 1;
        length = ROUND(pow(2.0, (double) order));
        /*
         * only read as many points as length of transform
         */
        if (length < nan) nan = length;
        /*
         * create SPEC file header and fill in universal portion
         */
        oh = new_header(FT_SPEC);
        oh->common.tag = YES;
        (void) strcpy(oh->common.prog, ProgName);
        (void) strcpy(oh->common.vers, Version);
        (void) strcpy(oh->common.progdate, Date);
        oh->variable.refer = iname;
        add_source_file(oh, iname, ih);    /*always do this before new comments*/
        (void) add_comment(oh, get_cmd_line(argc, argv));
        /*
         * fill in type-specific part of SPEC header
         */
        oh->hd.spec->start = first;
        oh->hd.spec->nan = nan;
        oh->hd.spec->frmlen = nan;
        oh->hd.spec->win_type = NONE;
        oh->hd.spec->sf = ih->hd.sd->sf;
        oh->hd.spec->dcrem = 0.0;
        oh->hd.spec->voicing = NO;
        oh->hd.spec->freq_format = SYM_EDGE;
        oh->hd.spec->spec_type = ST_DB;
        oh->hd.spec->contin = YES;
        oh->hd.spec->num_freqs = length/2 + 1;
        oh->hd.spec->pre_emp = NULL;
        oh->hd.spec->frame_meth = FM_FIXED;
        /*
         * add generic header items
         */
        *add_genhd_l("fft_length", NULL, 1, oh) = length;
        /*
         * write SPEC file header and allocate SPEC record
         */
        write_header(oh, ofile);
        spec_rec = allo_spec_rec(oh); 
        /*
         * move to starting position in SD file
         */
        if (first > 1) skiprec(ifile, first - 1, size_rec(ih));
        /*
         * main loop
         */
        logscale = 10 * log10(1.0);
        position = first;
        for (i = 0; i < nframes && more; i++) {
            /*
             * initialize data arrays
             */
            for (j = 0; j < length; j++) x[j] =  y[j] = 0.0;
            /*
             * get sampled data and perform fft
             */
            if (get_sd_recf(x, (int) nan, ih, ifile) == EOF) {
                more = 0;
                Fprintf(stderr, "%s: WARNING, EOF reached in input file\n", ProgName);
            }
            get_fft(x, y, order);
            /*
             * fill in and write out spectral record
             */
            spec_rec->tag = first;
            for (j = 0; j < oh->hd.spec->num_freqs; j++)
                spec_rec->re_spec_val[j] = logscale + 10 * log10(x[j]*x[j] + y[j]*y[j]);
            spec_rec->tag = position;
            position += nan;
            put_spec_rec(spec_rec, oh, ofile);
        }
    
    /*
     * put SD file info into ESPS common
     */
        if (strcmp(iname, "<stdout>") != 0) {
    	(void) putsym_s("filename", iname);
    	(void) putsym_s("prog", ProgName);
    	(void) putsym_i("start", (int) first);
    	(void) putsym_i("nan", (int) nan);
        }    
        exit(0);
    }

    void
    get_range(srec, erec, rng, rflag)
    long *srec;			/* starting record */
    long *erec;			/* end record */
    char *rng;			/* range string from range option */
    int rflag;			/* flag for whether range option used */
    {
        *srec = 1;
        *erec = LONG_MAX;
        if (rflag) 
    	lrange_switch (rng, srec, erec, 1);	
        else {
    	if(symtype("start") != ST_UNDEF) *srec = getsym_i("start");
    	if(symtype("nan") != ST_UNDEF) *erec = *srec + getsym_i("nan") - 1; 
        }
    }
    
.fi
.vE