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