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