feaop.1

speech signal process tools

(second form), or 1 (third form).
.IP
This option may be used at most twice.
If used once, it applies to both input files.
If used twice, it applies to
.I file1.in
the first time and
.I file2.in
the second time.
If the option is used twice and implies inconsistent values of
.I nan,
a warning message may be issued.
For example 
.BR \-r " 1" : 10
and
.BR \-r " 101" : 120
in the same
.I arrop
command will generate a warning of inconsistent
.B \-r
options
(unless
.B \-R
is in effect).
On the other hand two options with one unspecified endpoint, like
.BR \-r " 1" :
and
.BR \-r " 101" : 120,
are not considered inconsistent and will not generate the warning.
The warnings can be suppressed by the
.B \-z
option.
.TP
.BI \-t " output_type"
Specifies the type of the output field.
Allowable values are
DOUBLE, FLOAT, LONG, SHORT, BYTE, (or CHAR), DOUBLE_CPLX, FLOAT_CPLX,
LONG_CPLX, SHORT_CPLX, and BYTE_CPLX.
The case doesn't matter:  upper is not distinguished from lower.
With one exception, the default is the ``cover type'' of the input types;
see the DISCUSSION and the
.IR cover_type (3\-ESPS)
manual page for details.
The exception is that when the operation being performed is CPLX,
and the input types are both real, the default output type is the complex
type corresponding to the ``cover type'' of the input types.
Note that if you combine real input fields with a complex gain factor
(see
.BR \-g ),
you will need to specify a nondefault output type with
.B \-t
to obtain the intended complex result.
.TP
.BI \-x " debug_level \fR[0]\fP"
If 
.I debug_level
is positive,
.I feaop
prints debugging messages and other information
on the standard error output.
The messages proliferate as the  
.I debug_level
increases.
If \fIdebug_level\fP is 0 (the default), no messages are printed.  
.TP
.B \-z
Suppress warning messages.
.TP
.B \-I
Interchange the operands.
Normally, each value from
.I file1.in
(possibly scaled) is used as the first operand of the operation,
with a value from
.I file2.in
as the second operand.
When
.B \-I
is used, however, the possibly scaled values from
.I file1.in
are each used as the second operand
with a value from
.I file2.in
as the first operand.
Thus, if DIV is the operation, this option allows you to divide
.I in_field2
by
.I in_field1
instead of the reverse.
.TP
.BI \-O " operation" " \fR[ADD]"
Specifies the operation to be performed.
The possible operations are those supported by 
.IR arr_op (3\-ESPSsp)
and include ADD, SUB, MUL, DIV, PWR, and CPLX;
see the DISCUSSION section and the
.I arr_op
manual entry.
The case doesn't matter; upper is not distinguished from lower,
and "add" (or "aDd") will do as well as "ADD".
The default, ADD, specifies addition.
.TP
.BI \-P " param_file \fR[params]\fP"
uses the parameter file 
.I param_file
rather than the default, which is "params". 
.TP
.B \-R
``Recycle.''
If records from
.I file1.in
(or the subrange specified with
.BR \-r )
are exhausted before the end of the data from
.I file2.in,
they are reused cyclically as often as necessary.
.SH ESPS PARAMETERS
.PP
The parameter file does not have to be present,
since all the parameters have default values.
The following parameters are read, if present, from the parameter file:
.TP
.I "gain_real \- float"
.TP
.I "gain_imag \- float"
.IP
The real part and the imaginary part of the gain factor
.I g
by which values from
.I in_field1
are multiplied before being used as operands.
The defaults are 1 and 0.
These parameters are not read if the
.B \-g
option is used.
.TP
.I "in_field1 \- string"
.TP
.I "in_field2 \- string"
.IP
The names of the selected data fields in
.I file1.in
and
.I file2.in,
respectively.
The default for both is "samples".
These parameters are not read if the
.B \-f
option is used.
.TP
.I "nan \- int array" " or " "int"
.IP
The number of records to process in each input file.
This is either a scalar, applying to both files,
or a two-element array, giving separate values for the two files.
A value of 0, the default for both files, means continue processing
until the end of the file is reached.
If the
.B \-R
option is not in effect,
and two different non-default
.I nan
values are specified,
a warning is given, and the smaller value is used.
This parameter is not read if the
.B \-r
option is used.
.TP
.I "operation \- string"
.IP
The operation performed.
Allowable values include "add", "sub", "mul", "div", "pwr", and "cplx"
(case-insensitive).
This parameter is not read if the
.B \-O
option is used.
The default, "add" performs addition.
.TP
.I "out_field \- string"
.IP
The name of the output field in which the results are stored.
The default is as described for the
.B \-f
option.
This parameter is not read if
.B \-f
is used three times.
.TP
.I "output_type \- string"
.IP
The data type of the output field,
.I out_field.
Allowable values are
double, float, long, short, byte (or char), double_cplx, float_cplx,
long_cplx, short_cplx, and byte_cplx (case insensitive).
The default depends on the input types; see
.BR \-t ,
the DISCUSSION, and the
.IR cover_type (3\-ESPS)
manual page for details.
The parameter is not read if the
.B \-t
option is used.
.TP
.IR "start \- int array" " or " "int"
.IP
Either a two-element array,
containing the starting record numbers in the input files,
or a scalar, applying to both input files.
The default is {1, 1}, meaning the beginning of each file.
This parameter is not read if the
.B \-r
option is used.
.SH ESPS COMMON
.PP
The ESPS Common file is not read.
.PP
If Common processing is enabled,
and the output file is not standard output,
the program writes the Common parameters
.I prog,
.I filename,
.I start,
and
.I nan
to record the program's name, the name of the output file,
the starting record number of the output file (always 1),
and the number of points in the output file.
.PP
ESPS Common processing may be disabled
by setting the environment variable USE_ESPS_COMMON to
.I off.
The default ESPS Common file is
.I espscom
in the user's home directory.
This may be overridden
by setting the environment variable ESPSCOM to the desired path.
User feedback of Common processing is determined
by the environment variable ESPS_VERBOSE, with 0 causing no feedback
and increasing levels causing increasingly detailed feedback.
If ESPS_VERBOSE is not defined, a default value of 3 is assumed.
.SH ESPS HEADERS
.PP
The header of
.I file.out
is a copy of the header of
.I file2.in,
including all generic header items.
The generic header item
.I start_time
is written (or rewritten) with a value computed by taking the
.I start_time
from the header of
.I file2.in
(or zero, if the item doesn't exist)
and adding to it the relative time from the first record
in that file to the first record processed.
The computation of
.I start_time
depends on the value of the generic header item
.I record_freq
in
.I file2.in.
If that item isn't present,
.I start_time
is just copied from
.I file2.in
to
.I file.out.
The items
.I start
and
.I nan
are written (or rewritten) to contain the starting record number
and number of records to be processed in
.I file2.in
(with
.IR nan " = 0"
implying all records from
.I start
up to the end of the file).  Items
.I start1
and
.I nan1
record the same information for
.I file1.in.
Generic header items are added for the
.I operation,
.I gain_real,
.I gain_imag,
.I in_field1,
.I in_field2,
and
.I out_field
parameters.
As usual, the command line is added as a comment,
and the headers of the input files are added as source files to the output.
.SH FUTURE CHANGES
.PP
An option may be added to allow
.I file1.in
to be omitted and a single constant operand to be specified instead.
The conformability requirements on the two input fields
may be made more flexible.
Any additions to the list of operations accepted by
.IR arr_op (3\-ESPS)
will be reflected in this program.
.SH EXAMPLES
.PP

.SH ERRORS AND DIAGNOSTICS
.PP
If an unknown option is specified, if
.B \-f
is used more than three times, if
.B \-r
is used more than twice,
or if the number of file names is wrong,
.I feaop
prints a synopsis of command-line usage and exits.
.PP
The program exits with an error message if any of the following are true:
an unknown operation name is specified;
an input file does not exist or is not an ESPS FEA file;
both input file names are "\-";
an input file name is the same as the output name (but not "\-");
an input field does not exist in the respective file;
the input fields have different numbers of elements;
the output type is not known or nonnumeric;
a bad range is specified with
.B \-r.
.PP
The program issues a warning and continues
if the files do not have the same value of the header item
.I record_freq.
(For sampled-data files, that means that the sampling frequencies mismatch.)
It also warns if
an explicit output field (that is, one not specified with
.BR \-f \-)
already exists in
.I file2.in,
if the input fields have different ranks or dimensions
(but the same number of elements), if two
.B \-r
options specify inconsistent ranges (see the discussion of
.BR \-r ),
or if an input file ends before a specified endpoint.
.SH BUGS
.PP
None known.
.SH REFERENCES
.PP
.SH "SEE ALSO"
.PP
.IR addsd (1\-ESPS),
.IR feafunc (1\-ESPS),
.IR multsd (1\-ESPS),
.IR mux (1\-ESPS).
.IR select (1\-ESPS),
.IR arr_op (3\-ESPS),
.IR cover_type (3\-ESPS),
.IR type_convert (3\-ESPS)
.IR FEA_SPEC (5-ESPS)
.SH AUTHOR
.PP
Rod Johnson