NAME

       mst_addmsr - Add time coverage and data samples to MSTrace structures

SYNOPSIS

       #include <libmseed.h>

       int    *mst_addmsr ( MSTrace *mst, MSRecord *msr, flag whence );

       int     mst_addspan ( MSTrace *mst, hptime_t starttime, hptime_t endtime,
                             void *datasamples, int64_t numsamples,
                             char sampletype,  flag whence );

       MSTrace  *mst_addmsrtogroup ( MSTraceGroup *mstg, MSRecord *msr,
                                     flag dataquality, double timetol,
                                     double sampratetol );

       MSTrace  *mst_addtracetogroup ( MSTraceGroup *mstg, MSTrace *mst );

DESCRIPTION

       These  routines  provides  different  ways  of adding time coverage to MSTrace objects.  A
       common way to organize MSTrace objects is  with  a  MSTraceGroup.   The  mst_addmsrtogroup
       provides  a  convenient  way  to  add  MSRecord data to a MSTraceGroup, hiding many of the
       details of MSTrace matching and bookkeeping.

       mst_addmsr will add the time coverage from a MSRecord to a MSTrace.  The start or end time
       will be updated and data samples copied if they exist.  No checking is done to verify that
       the record matches the trace in any way.  If whence is 1 the  MSRecord  coverage  will  be
       added  at  the  end of the MSTrace.  If whence is 2 the MSRecord coverage will be added at
       the beginning of the MSTrace.

       mst_addspan does the same thing as msr_addmsr except that time coverage and  data  samples
       are  explicitly  provided.   See  ms_time(3) for a description of the high precision epoch
       time format  needed  for  starttime  and  endtime.   See  the  Waveform  Data  section  of
       ms_intro(3) for a description of data sample representation.

       mst_addmsrtogroup  adds  time  coverage  from the specified MSRecord to the first adjacent
       MSTrace found in the specified MSTraceGroup.  If the dataquality flag is true traces  will
       be  grouped by quality in addition to the source name identifiers.  mst_findadjacent(3) is
       used with the specified sample rate and time tolerances to find  an  adjacent  trace,  see
       mst_findadjacent(3)  for  further  details.  If no adjacent MSTrace is found a new MSTrace
       will be added to the MSTraceGroup.

       mst_addtracetogroup adds a MSTrace structure to a MSTraceGroup structure.  The MSTrace  is
       added at the end of the MSTrace chain.

RETURN VALUES

       mst_addmsr and mst_addspan return 0 on success and -1 on error.

       mst_addmsrtogroup returns a pointer to the MSTrace updated or 0 on error.

       mst_addtracetogroup returns a pointer to the MSTrace added or 0 on error.

SEE ALSO

       ms_intro(3), mst_init(3), mst_findadjacent(3) and ms_time(3).

AUTHOR

       Chad Trabant
       IRIS Data Management Center