.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved.\" @(#)esps.5t	1.2 7/15/87 ESI.TH ESPS 5\-ESPS 7/15/87.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc..SH NAMEESPS Data File Header.SH SYNOPSIS.B #include <sps/header.h>.SH DESCRIPTION.PPAll ESPS data files have a header that consists of two parts.  The firstpart contains header items that are common to all ESPS data files.   Thispart of the header should contain all information required by ESPS programsthat can operate on any type of data file.   After this section of theheader comes the type specific part.   This part of the header containsitems are are appropriate for specific types of ESPS data files.   Theyare declared in a union, so that the correct one can be referenced by ESPS programs, depending on the type of the file, as indicated by the typecode in the header.    Additional types may be added as required..PPThe file type specific header items are described in the manualpages for those file types.   For example, to understand theheader structure of the ESPS sampled data file, it is necessary to refer to this manual page and \fISD\fR(5\-ESPS).    .PPIn addition, there is support for \fIgeneric\fR header items that canbe created at run-time.  These are held in a data structure in thefile header..PPThe header has the following layout as defined by.I <sps/header.h>.PP.nf/* * Structure of a ESPS data file header */.br.PP.nfstruct header {.sp/\(**  fields common to all ESPS headers  \(**/.sp    struct fixsiz {.TSl1 l1 l1 l.    short	type;	/\(** file type \(**/    int	check;	/\(** check field  \(**/    char	date[DATESIZE];	/\(** file creation date \(**/    char	hdvers[VERSIONSIZE];	/\(** header version \(**/    char	prog[PROGSIZE];	/\(** program name \(**/    char	vers[VERSIONSIZE];	/\(** prog version \(**/    char	progdate[DATESIZE];	/\(** prog compile date \(**/    long	ndrec;	/\(** number of data records \(**/    short	tag;	/\(** YES if data has tag \(**/    short	ndouble;	/\(** number of doubles \(**/    short	nfloat;	/\(** number of floats \(**/    short	nlong;	/\(** number of longs \(**/    short	nshort;	/\(** number of shorts \(**/    short	nchar;	/\(** number of chars \(**/    short	fixsiz;	/\(** fixed header size \(**/    long	hsize;	/\(** total header size \(**/    char	user[USERSIZ];	/\(** user that created file \(**/    short	spares[NSPARES];	/\(** spares \(**/.T&l1 l1 l1 l.    } common;.sp.bp    struct varsize {.T&l1 l1 l1 l.    char	*source[MAX_SOURCES];	/\(** pointers to src		file names \(**/    struct header	*srchead[MAX_SOURCES];	/\(** pointers to src		headers \(**/    char	*typtxt;	/\(** text field \(**/    char	*comment;	/\(** comment field \(**/    char	*refer;	/\(** reference file for tags \(**/    struct header	*refhd;	/\(** pointer to special reference header \(**/    short	nnames;	/\(** number of source file names \(**/    short	nheads;	/\(** number of source file 		headers \(**/    struct gen_hd	*gentab[GENTABSIZ];	/\(** generic item 		symbol table \(**/    short	ngen;	/\(** number of generic items \(**/.TE    } variable;.nf.sp/* Type specific portion of the header */.sp.TSl1 l1 l1 l.	union {		struct sd_header *sd;	/\(** sampled data files \(**/		struct pit_header *pit;	/\(** pitch files \(**/		struct ana_header *ana;	/\(** analysis files \(**/		struct spec_header *spec;	/\(** spectral files \(**/			struct ros_header *ros;	/\(** rosetta speech frame files \(**/		struct filt_header *filt;	/\(** filter files \(**/		struct scbk_header *scbk;	/\(** scaler codebook file \(**/		struct fea_header *fea;	/\(** feature file \(**/	} hd;};.TE.PPZ domain functions are represented by the following structure;.sp.TSl1 l1 l1 l.struct zfunc {  short	nsiz;	/\(** length of numerator polynomial \(**/  short	dsiz;	/\(** length of denominator polynomial \(**/  float	*zeros;	/\(** pointer to numerator polynomial \(**/  float	*poles;	/\(** pointer to denominator polynomial \(**/};.TE.PPThe gentab symbol table is a hash table of pointers to the followingstructure.   Conflicts in the hash function are resolved by chainingnodes together..sp.TSl1 l1 l1 l.struct gen_hd {  char *name;	/\(** symbol name \(**/  unsigned int size;	/\(** size of item \(**/  short type;	/\(** type of symbol \(**/  char *d_ptr;	/\(** pointer to data \(**/  char **codes;	/\(** codes for CODED data type \(**/  struct geh_hd *next;	/\(** next in chain \(**/};.TE.fi.PPThe following items are all in the fixed portion of the pitch fileheader..IP type This field is set to the type code for the ESPS file. File type codes are defined in \fI<sps/ftypes.h>\fR.This field should not be altered by a application programs.    It is setby the header access programs..IP checkThis field is used by the header access routines as a check that thisis really a ESPS file header.   It stores the special valueHD_CHECK_VAL.  This field should not be altered by applicationprograms..IP dateThe date/time that this data file was created.  The format is thatreturned by \fIctime\fR(3).   This field should not be altered byapplication programs.   It is set by the header access programs..IP hdversThis field contains the version number of \fI<sps/header.h>\fR in use whenthis header was created.  It is set by the header access programs andshould not be altered by application programs.For embedded headers, this will be the version of the current headerstructure (relative to the binary of the program involved) and notnecessarily the version when the original data file was created..IP progThe name of the program that created this data file..IP versThe version of the program that created this data file..IP progdateThe date/time that the program that created this file was compiled.The format of the date/time is the same as \fIdate\fR..IP ndrecWhen a disk file is read by \fIread_header\fP, this field is set tothe number of data records in the file.  If a pipe is being read,then this field is set to -1.  Programs should not set this field,and they must not rely on the value of this field if the input is tobe a pipe.  Normally, ESPS programs should be written to work withpipes so ndrec should not be used.  If it is used, the restrictionthat pipes cannot be used must be documented on the manual page.Note that \fIpsps\fP (1\-ESPS) does display the value of ndrec; thus,If the number of records must be known before processing and and youstill want to accept data from a pipe, an alternative is to write thepipe data to a temporary file.  Note that \fIpsps\fP (1\-ESPS) doesdisplay the value of ndrec; thus, when \fIpsps\fP is run on a diskfile, the number of records is displayed correctly..IP tagThis field is YES if the data records are preceded by a tag.Otherwise this field is equal to NO.If a tag is present, it is not counted in the length of data recordcomputation..LPThe type of the data in the file is given by the nextfive header items.    If a data structure contains more than a single data type, then they always will occur in the followingorder by type; doubles, floats, longs, shorts, and chars.   Thefollowing header items give the number of records by each type.A general purposeapplication program should be able to determine the record structurefrom this information.See \fIwrite_header\fR(3\-ESPSu) and \fIset_sd_type\fR(3\-ESPSu).The position tag field, if present, is not included here..IP ndoubleThe number of double precision data types in the data record..IP nfloatThe number of floating point data types..IP nlongThe number of long data types..IP nshortThe number of short data types..IP ncharThe number of char data types..IP fixsizSize of the fixed portion of the header in 32-bit words.  This fieldshould not bewritten into by application programs.  This field is filled in by \fIwrite_header\fR(3\-ESPSu)..IP hsizeTotal header size in 32-bit words.  May be used to locate the firstdata point.  This field is filled in by \fIwrite_header\fR(3) andshould not be written into by application programs..IP userThe name (first 8 characters) of the username (login name) when thisESPS file was created.   This field is filled in by\fIwrite_header\fR(3\-ESPSu) and should not be written into byapplication programs..IP sparesThere are NSPARES short words available for future use..IP sourceA pointer to a source  file name stored as a null-terminated string.The order of the source files (if there is more than one) issignificant and is assumed to be order that the files wereprocessed.  There may be up to MAX_SOURCES source file names.See \fIadd_source_file\fR(3\-ESPSu)..IP srcheadA pointer to another ESPS header.    The order is assumedto correspond to the order of \fIsource\fR as described above.See \fIadd_source_file\fR(3\-ESPSu)..IP typtxtPointer to a NULL terminated string.   The maximum length of this string is MAX_STRING characters.   This field is intended to be used as a plot label or title.For a reasonably short sampled data file, this field will often containthe text of the sampled speech.See \fIsavestring\fR(3\-ESPSu)..IP commentThis is also a pointer to a NULL terminated string of maximum lengthMAX_STRING.  This string is intended to be used for a runningcommentary as the file is taken through various processing stages.The NULL terminated string may consist of NEW_LINE terminatedsubstrings.See \fIadd_comment\fR(3\-ESPSu)..IP referA NULL terminated string of the name of a reference file relevant toa tag that might be in the data record.See \fIsavestring\fR(3\-ESPSu)..IP refhdA pointer to a special ESPS header.  Unlike the header pointers\fIsrchead\fR, \fIrefhd\fR is not intended for use in keeping histories.Rather, it is used to retain reference information when needed byparticular programs.  (For example, it is needed in FEA file processingto maintain information about field derivations \- see\fIfea_stat\fR(1\-ESPS)..IP nnamesThe number of source file names in \fIsource\fR..IP nheadsThe number of source file headers in \fIsrchead\fR..SH FILES/usr/include/sps/header.h.SH SEE ALSOANA(5\-ESPS), FILT(5\-ESPS), ROS(5\-ESPS), SD(5\-ESPS), PIT(5\-ESPS), SCBK(5\-ESPS), FEA(5\-ESPS), read_header(3\-ESPSu),write_header(3\-ESPSu), savestring(3\-ESPSu), add_comment(3\-ESPSu),add_genhd(3\-ESPSu), get_genhd(3\-ESPSu), genhd_list(3\-ESPSu),genhd_type(3\-ESPSu).SH FUTURE CHANGES.SH AUTHOROriginal design by Joe Buck.  This version by Alan Parker.