NAME

     mvstak  - vertically operate (+,-,*,/) on traces from n data
     sets

SYNOPSIS

     mvstak [ [ -N,-N,...,-Nntap(i) ] [ -Fftap ] ] [ -Ootap  ]  [
     -operoper[1-n] ] [ -norm ] [ -m ] [ -V ] [ -? ]

DESCRIPTION

     mvstak reads traces from n data sets and  operates  (adding,
     subtracting,  multiplying,  dividing)  them vertically, i.e.
     trace 1 from  ntap(1)  stacked  with  trace  1  from  ntap2,
     stacked  with trace 3 from ntap3, etc, is output as trace 1;
     trace 2 from ntap2 is stacked with trace 2 from ntap2,  etc,
     and output as trace 2...

     This is the ideal tool in XIKP to gather  up  parallel  pro-
     cessed streams and stack them, e.g. those sent out by splitr
     or or gather.  The only restriction is that  the  number  of
     samples  per  trace, the number of trace per record, and the
     number of records for each stream be identical. A maximum of
     1000  files  is allowed but most computer systems have built
     in limits considerably smaller than this - beware  of  these
     limitations.

     Using mvstak on the command line it is sometimes easier  for
     large  numbers  of  input files to put those file names in a
     file and read that file to extract  the  actual  input  file
     names.  One  can either read file names by using multiple -N
     entries or by using the file of file names option.

     mvstak gets both its data and its  parameters  from  command
     line arguments.  These arguments specify the inputs, output,
     whether the data are trace or record oriented,  and  verbose
     printout, if desired.

  Command line arguments
     -N,-N,...,-N ntap(i)
          Enter each input data  set  name  or  file  immediately
          after  typing  -N (a maximum number of 1000 input files
          is allowed).  This input file should include  the  com-
          plete  path  name  if  the  file resides in a different
          directory.  Example -N0/b/vsp/dummy tells  the  program
          to  look  for file 'dummy' in directory 'vsp' stored on
          the 'b' disk. Optionally...

     -F ftap

     -O otap
          Enter the output data  set  name  or  file  immediately
          after typing -O.  This output file is not required when
          piping the output to another process.  The output  data
          set also requires the full path name (see above).

     -oper oper[1-n]
          Enter a string enclosed  in  either  single  or  double
          quotes  containing  the  arithmetic operands +,-,/,* to
          apply between the input data sets, i.e. the input  data
          streams are ordered from 1 -> n (left to right) so that
          if the ith operand is a "+" it means  traces  from  the
          ith  stream are added to the i+1th stream.  If only one
          operand is  given  then  it  is  applied  to  all  data
          streams,  e.g.  -oper"*" means all data streams will be
          vertically multiplied.  The default is  "+",  i.e.  all
          dada streams will be vertically stacked.

     -m   Enter the command line argument '-m' to flag the  input
          data  as  trace  oriented  (as  opposed  to the default
          record oriented).  This is important for mvstak to know
          to  prevent  the  entire  process from hanging.  If the
          input data are  assumed  to  be  record  oriented  then
          mvstak  will  try  to  read  record 1 from stream 1 and
          stack it with record 1 from stream 2 and stack it  with
          record  1 from stream 3, etc, until all record 1's have
          been consumed and stacked.  This result is then  output
          as  record  1.   This  process is then repeated for the
          next input record from each of the streams, and  so  on
          until  all the data from all the streams have been con-
          sumed.  If the data are assumed to  be  trace  oriented
          then  trace  1  is  read from stream 1 and stacked with
          trace 1 from stream 2 and stacked  with  trace  1  from
          stream  3,  etc, until all the trace 1's have been con-
          sumed and stacked.  This result is then output as trace
          1. This process is then repeated for all the trace 2's,
          then all the trace 3's, and so on through the data set.
          Across networks (if that's your gig) it is usually more
          efficient to trade in larger units of data  like  whole
          records.  This might influence your decision when using
          XIKP In general if your upstream processes  are  record
          oriented  the  use the default mode; if they are trace-
          by-trace process then try the trace mode.

     -norm
          Enter the command line argument  '-norm'  to  normalize
          summed  output.  This can only be used if the operators
          are all summations, i.e. +

     -V   Enter the command line argument '-V' to get  additional
          printout.

     -?   Enter the command line  argument  '-?'  to  get  online
          help.   The program terminates after the help screen is
          printed.

BUGS

     Special precautions must be taken by mvstak when  using  the
     divide  (/)  option  because  of the possibility of at least
     some samples being zero.  A check is made to see if a sample
     is zero in which case the division is bypassed for that sam-
     ple only.

See Also

     XIKP, splitr, gather

COPYRIGHT

     copyright 2001, Amoco Production Company
               All Rights Reserved
          an affiliate of BP America Inc.