NAME

       mst_findmatch - Searching a MSTraceGroup for specific MSTrace structures.

SYNOPSIS

       #include <libmseed.h>

       MSTrace  *mst_findmatch ( MSTrace *startmst, char dataquality,
                                 char *network, char *station,
                                 char *location, char *channel );

       MSTrace  *mst_findadjacent ( MSTraceGroup *mstg,
                                    flag *whence, char dataquality,
                                    char *network, char *station,
                                    char *location, char *channel,
                                    double samprate, double sampleratetol,
                                    hptime_t starttime, hptime_t endtime,
                                    double timetol);

DESCRIPTION

       mst_findmatch  traverses  a MSTrace chain starting at startmst and returns the first entry
       that matches the source name identifiers.  If dataquality is not zero it must  also  match
       the found entry.  A calling program commonly calls this routine in a loop in order to find
       all matching MSTraces in a MSTraceGroup.

       mst_findadjacent finds the first entry in the MSTraceGroup pointed to by mstg that matches
       the  given  source name identifiers and is time adjacent to the time coverage described by
       the samprate, starttime and endtime.  If dataquality is not zero it must  also  match  the
       found  entry.   See  ms_time(3)  for a description of the high precision epoch time format
       needed for starttime and endtime.

       The tolerance for sample rate and time matching can also be specified.  If sampratetol  is
       -1.0  the  default  tolerance  of abs(1-sr1/sr2) < 0.0001 is used.  If timetol is -1.0 the
       default time tolerance of 1/2 the sample period will be used.  If sampratetol  or  timetol
       is  -2.0  the  respective tolerance check will not be performed.  If time tolerance is not
       checked whence will be set to whichever end fits best.  The time tolerance is specified in
       seconds.

       When  an  adjacent  MSTrace  is  found  the  whence flag will be set to indicate where the
       indicated time span is adjacent in the following way:

       1: time span fits at the end of the MSTrace
       2: time span fits at the beginning of the MSTrace

RETURN VALUES

       mst_findmatch returns a pointer to the matching MSTrace structure or 0 if no  match  found
       or error.

       mst_findadjacent  returns  a pointer to the adjacent MSTrace structure and the whence flag
       is set when an adjacent MSTrace is found or 0 when no adjacent MSTrace is found.

SEE ALSO

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

AUTHOR

       Chad Trabant
       IRIS Data Management Center