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

Libmseed API                                       2013/05/17                                      MST_ADDMSR(3)