Provided by: libmseed-doc_2.19.5-1_all bug

NAME

       ms_selection - Routines to manage and use data selection lists.

SYNOPSIS

       #include <libmseed.h>

       Selections *ms_matchselect ( Selections *selections, char *srcname,
                                    hptime_t starttime, hptime_t endtime,
                                    SelectTime **ppselecttime );

       Selections *msr_matchselect ( Selections *selections, MSRecord *msr,
                                     SelectTime **ppselecttime );

       int  ms_addselect ( Selections **ppselections, char *srcname,
                          hptime_t starttime, hptime_t endtime );

       int  ms_addselect_comp ( Selections **ppselections, char *net,
                                char *sta, char *loc, char *chan, char *qual,
                                hptime_t starttime, hptime_t endtime );

       int  ms_readselectionsfile ( Selections **ppselections, char *filename );

       void ms_freeselections ( Selections *selections );

       void ms_printselections ( Selections *selections );

DESCRIPTION

       These  routines serve as a convienence facility for creating a list of data selections and
       using it to match data.  The selection criteria are the srcname and optional start and end
       times.  The srcname components in a selection may contain globbing characters for matching
       (wildcards, character range, etc.).  A srcname is generally composed of network,  station,
       location,  channel  and  optional  quality  components;  normally  these  are created with
       msr_srcname(3) and mst_srcname(3).

       ms_matchselect checks for an entry in  the  selections  list  that  matches  the  supplied
       srcname  and  optionally  starttime and endtime.  The start and/or end times can be set to
       HTPERROR to mean "any" time.  A selection will match the specified time range if there  is
       any  overlap  in time coverage.  If the ppselecttime pointer is not NULL it will be set to
       the matching SelectTime entry.

       msr_matchselect is a simple wrapper to  call  ms_matchselect  using  the  details  from  a
       specified MSRecord.

       ms_addselect  adds  a  selection  entry to the selections list based on the rcname and the
       starttime and endtime  boundaries.   The  source  name  components  may  contain  globbing
       characters  for  matching  including  wildcards  and  character sets, see SRCNAME MATCHING
       below.  Note that the ppselections is a pointer to a pointer, if the secondary pointer has
       not  been  allocated  (i.e.  the  list  is  empty) the first entry will be created and the
       primary pointer updated.

       ms_addselect_comp is a wrapper of ms_addselect used  to  add  a  selection  entry  to  the
       selections  list.   The  net,  sta,  loc, chan and qual source name components are used to
       create a srcname.  The name  components  may  contain  globbing  characters  for  matching
       including  wildcards  and character sets, see SRCNAME MATCHING below.  If a name component
       is not specified a wildard matching all entries will be subsituted, i.e. net==NULL will be
       interpreted  to  match  all  network codes.  As a special case a loc value of "--" will be
       translated to and empty string to match the srcname  representation  of  a  blank  (space-
       space) location ID.

       ms_readselectionsfile  reads  a  file containing a list of selections and adds them to the
       specified selections list.  As with ms_addselect if the selections list is empty  it  will
       be created.  For more details see the SELECTION FILE section below.

       ms_freeselections frees all memory associated with selections.

       ms_printselections  prints  all  of  the entries in the selections list using the ms_log()
       facility.

RETURN VALUES

       The  ms_matchselect  and  msr_matchselect  routines  return  a  pointer  to  the  matching
       Selections  entry  on  success and NULL when no match was found.  These routines will also
       set the ppselecttime pointer to the matching SelectTime entry if supplied.

       ms_addselect and ms_addselect_comp return 0 on success and -1 on error.

       ms_readselectionsfile returns the number of selections added to the list or -1 on error.

SELECTION FILE

       A selection file is used to match input data records based on network,  station,  location
       and  channel  information.   Optionally a quality and time range may also be specified for
       more refined selection.  The non-time fields may use the '*' wildcard  to  match  multiple
       characters  and  the  '?' wildcard to match single characters.  Character sets may also be
       used, for example '[ENZ]' will match either E, N or Z.  The '#'  character  indicates  the
       remaining portion of the line will be ignored.

       Example selection file entries (the first four fields are required)
       #net sta  loc  chan  qual  start             end
       IU   ANMO *    BH?
       II   *    *    *     Q
       IU   COLA 00   LH[ENZ] R
       IU   COLA 00   LHZ   *     2008,100,10,00,00 2008,100,10,30,00

SRCNAME MATCHING

       Entries  in  a  Selections  list  include  a  "source  name" (srcname) string to represent
       matching parameters for network, station, location, channel  and  optionally  the  quality
       name  components.   Each name component may contain globbing characters to match more than
       one unique srcname.

       Valid glob patterns include:
          *       matches zero or more characters
          ?       matches any single character
          [set]   matches any character in the set
          [^set]  matches any character NOT in the set
                  where a set is a group of characters or ranges. a range
                  is written as two characters separated with a hyphen:
                  a-z denotes all characters between a to z inclusive.
          [-set]  set matches a literal hyphen and any character in the set
          []set]  matches a literal close bracket and any character in the set

          char    matches itself except where char is '*' or '?' or '['

        examples:
          a*c             ac abc abbc ...
          a?c             acc abc aXc ...
          a[a-z]c         aac abc acc ...
          a[-a-z]c        a-c aac abc ...

EXAMPLE USAGE

       The primary intention of the Selections list facility is  to  limit  data  to  a  specific
       selection as it's read into a program.  This is illustrated below.

       main() {
         MSRecord *msr = NULL;
         Selections *selections = NULL;
         hptime_t starttime;
         hptime_t endtime;
         int retcode;

         ms_addselect (&selections, "IU_*_*_LH?_?", HPTERROR, HPTERROR);

         starttime = timestr2hptime ("2009/1/15 00:00:00.00");
         endtime = timestr2hptime ("2009/1/31 23:59:59.99");
         ms_addselect (&selections, "IU_ANMO_00_LH?_?", starttime, endtime);

         while ( (retcode = ms_readmsr (&msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
           {
              /* Print details if data record matches selection criteria */
              if ( msr_matchselect (selections, msr, NULL) )
                {
                  msr_print (msr, verbose);
                }
           }

         if ( retcode != MS_ENDOFFILE )
           ms_log (2, "Error reading input file %s: %s\n",
                   filename, ms_errorstr(retcode));

         /* Cleanup memory and close file */
         ms_readmsr (&msr, NULL, 0, NULL, NULL, 0, 0, verbose);
       } /* End of main() */

       The following two calls are equivalent:
         ms_addselect (&selections, "IU_ANMO_00_LH?_?", starttime, endtime);
         ms_addselect_comp (&selections, "IU", "ANMO", "00", "LH?", "?", startime, endtime);

       As a further convienence usage of ms_readselectionsfile() would allow the selections to be
       specified in a simple ASCII file and avoid the need to directly call ms_addselect().

SEE ALSO

       msr_srcname(3) and mst_srcname(3).

AUTHOR

       Chad Trabant
       IRIS Data Management Center