MS_SELECTION(3)

🌸 MS_SELECTION(3) — Library Functions Manual 🌸

okay so bestie, this page is MS_SELECTION(3), straight out of the Library Functions Manual, and it's genuinely one of the most useful little things in libmseed. sit down, hydrate, let's go 💖

---

✨ NAME ✨

ms_selection — routines to manage and use data selection lists. that's it, that's the whole vibe. a list of "what data do i actually care about" that you can match records against. iconic. 👑

---

🦋 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 💅

so these routines are your little convenience facility for building a list of data selections and then using that list to match data. the selection criteria are the srcname plus an optional start time and end time. the srcname components inside a selection can totally contain globbing characters for matching — wildcards, character ranges, all of it. and a srcname is generally made up of network, station, location, channel and an optional quality component; normally you'd build those with msr_srcname(3) and mst_srcname(3).

ms_matchselect — this one goes looking through the selections list for an entry that matches the srcname you handed it, and optionally the starttime and endtime too. and here's the cute part: starttime and/or endtime can be set to HTPERROR to mean "any" time. a selection matches the time range you specified if there's any overlap at all in time coverage. oh and if the ppselecttime pointer isn't NULL, it gets set to the matching SelectTime entry. 🫶

msr_matchselect — literally just a simple wrapper that calls ms_matchselect using the details from an MSRecord you specify. low effort, high reward.

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 — peep SRCNAME MATCHING below. and bestie, heads up: ppselections is a pointer to a pointer, so if the secondary pointer hasn't been allocated yet (i.e. the list is empty), the first entry gets created and the primary pointer gets updated. it handles it for you, no stress. ✨

ms_addselect_comp — 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. those name components may contain globbing characters for matching, including wildcards and character sets — again, SRCNAME MATCHING below. if a name component isn't specified, a wildcard matching all entries gets substituted in its place, i.e. net==NULL will be interpreted as "match all network codes". and as a special case, a loc value of -- will be translated to an empty string, so it matches the srcname representation of a blank (space-space) location ID. the way that detail saves lives 😭

ms_readselectionsfile — reads a file containing a list of selections and adds them to the selections list you specified. same deal as ms_addselect: if the selections list is empty, it gets created. more deets in the SELECTION FILE section below. 🍓

ms_freeselections — frees all memory associated with selections. clean up after yourself, periodt.

ms_printselections — prints every entry in the selections list, using the ms_log() facility.

---

⭐ RETURN VALUES ⭐

• ms_matchselect and msr_matchselect 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 it was 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 you can also throw in a quality and a time range for a more refined selection. the non-time fields may use the '*' wildcard to match multiple characters and the '?' wildcard to match single characters. character sets work too — for example '[ENZ]' will match either E, N or Z. and the '#' character means the rest of that line gets ignored. noted. 💀

example selection file entries — and yes, 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 that represents the matching parameters for network, station, location, channel and optionally the quality name components. each name component may contain globbing characters so it can match more than one unique srcname. it's giving pattern matching but make it seismology.

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. and that looks a lil something like this:

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() */

and 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 convenience, using ms_readselectionsfile() would let the selections be specified in a simple ASCII file and save you from ever having to directly call ms_addselect(). obsessed with the efficiency honestly 💅

---

🔥 SEE ALSO 🔥

msr_srcname(3) and mst_srcname(3). go read those too, they're the whole reason your srcnames look right. 🦋

---

👑 AUTHOR 👑

Chad Trabait IRIS Data Management Center

---

this page came from the Libmseed API, dated 2012/12/28, and it lives at MS_SELECTION(3). that's the whole thing bestie — go build yourself a selections list and slay 🌸💖✨