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

Libmseed API                                       2006/02/27                                   MST_FINDMATCH(3)