1MS_SELECTION(3) Library Functions Manual MS_SELECTION(3)
2
6 ms_selection - Routines to manage and use data selection lists.
7
10 #include <libmseed.h>
11 Selections *ms_matchselect ( Selections *selections, char *srcname,
13 hptime_t starttime, hptime_t endtime,
14 SelectTime **ppselecttime );
15 Selections *msr_matchselect ( Selections *selections, MSRecord *msr,
17 SelectTime **ppselecttime );
18 int ms_addselect ( Selections **ppselections, char *srcname,
20 hptime_t starttime, hptime_t endtime );
21 int ms_addselect_comp ( Selections **ppselections, char *net,
23 char *sta, char *loc, char *chan, char *qual,
24 hptime_t starttime, hptime_t endtime );
25 int ms_readselectionsfile ( Selections **ppselections, char *filename );
27 void ms_freeselections ( Selections *selections );
29 void ms_printselections ( Selections *selections );
31
34 These routines serve as a convienence facility for creating a list of
35 data selections and using it to match data. The selection criteria are
36 the srcname and optional start and end times. The srcname components
37 in a selection may contain globbing characters for matching (wildcards,
38 character range, etc.). A srcname is generally composed of network,
39 station, location, channel and optional quality components; normally
40 these are created with msr_srcname(3) and mst_srcname(3).
41 ms_matchselect checks for an entry in the selections list that matches
43 the supplied srcname and optionally starttime and endtime. The start
44 and/or end times can be set to HTPERROR to mean "any" time. A selec‐
45 tion will match the specified time range if there is any overlap in
46 time coverage. If the ppselecttime pointer is not NULL it will be set
47 to the matching SelectTime entry.
48 msr_matchselect is a simple wrapper to call ms_matchselect using the
50 details from a specified MSRecord.
51 ms_addselect adds a selection entry to the selections list based on the
53 rcname and the starttime and endtime boundaries. The source name com‐
54 ponents may contain globbing characters for matching including wild‐
55 cards and character sets, see SRCNAME MATCHING below. Note that the
56 ppselections is a pointer to a pointer, if the secondary pointer has
57 not been allocated (i.e. the list is empty) the first entry will be
58 created and the primary pointer updated.
59 ms_addselect_comp is a wrapper of ms_addselect used to add a selection
61 entry to the selections list. The net, sta, loc, chan and qual source
62 name components are used to create a srcname. The name components may
63 contain globbing characters for matching including wildcards and char‐
64 acter sets, see SRCNAME MATCHING below. If a name component is not
65 specified a wildard matching all entries will be subsituted, i.e.
66 net==NULL will be interpreted to match all network codes. As a special
67 case a loc value of "--" will be translated to and empty string to
68 match the srcname representation of a blank (space-space) location ID.
69 ms_readselectionsfile reads a file containing a list of selections and
71 adds them to the specified selections list. As with ms_addselect if
72 the selections list is empty it will be created. For more details see
73 the SELECTION FILE section below.
74 ms_freeselections frees all memory associated with selections.
76 ms_printselections prints all of the entries in the selections list
78 using the ms_log() facility.
79
82 The ms_matchselect and msr_matchselect routines return a pointer to the
83 matching Selections entry on success and NULL when no match was found.
84 These routines will also set the ppselecttime pointer to the matching
85 SelectTime entry if supplied.
86 ms_addselect and ms_addselect_comp return 0 on success and -1 on error.
88 ms_readselectionsfile returns the number of selections added to the
90 list or -1 on error.
91
94 A selection file is used to match input data records based on network,
95 station, location and channel information. Optionally a quality and
96 time range may also be specified for more refined selection. The non-
97 time fields may use the '*' wildcard to match multiple characters and
98 the '?' wildcard to match single characters. Character sets may also
99 be used, for example '[ENZ]' will match either E, N or Z. The '#'
100 character indicates the remaining portion of the line will be ignored.
101 Example selection file entries (the first four fields are required)
103 #net sta loc chan qual start end
104 IU ANMO * BH?
105 II * * * Q
106 IU COLA 00 LH[ENZ] R
107 IU COLA 00 LHZ * 2008,100,10,00,00 2008,100,10,30,00
108
111 Entries in a Selections list include a "source name" (srcname) string
112 to represent matching parameters for network, station, location, chan‐
113 nel and optionally the quality name components. Each name component
114 may contain globbing characters to match more than one unique srcname.
115 Valid glob patterns include:
117 * matches zero or more characters
118 ? matches any single character
119 [set] matches any character in the set
120 [^set] matches any character NOT in the set
121 where a set is a group of characters or ranges. a range
122 is written as two characters separated with a hyphen:
123 a-z denotes all characters between a to z inclusive.
124 [-set] set matches a literal hyphen and any character in the set
125 []set] matches a literal close bracket and any character in the set
126 char matches itself except where char is '*' or '?' or '['
128 examples:
130 a*c ac abc abbc ...
131 a?c acc abc aXc ...
132 a[a-z]c aac abc acc ...
133 a[-a-z]c a-c aac abc ...
134
137 The primary intention of the Selections list facility is to limit data
138 to a specific selection as it's read into a program. This is illus‐
139 trated below.
140 main() {
142 MSRecord *msr = NULL;
143 Selections *selections = NULL;
144 hptime_t starttime;
145 hptime_t endtime;
146 int retcode;
147 ms_addselect (&selections, "IU_*_*_LH?_?", HPTERROR, HPTERROR);
149 starttime = timestr2hptime ("2009/1/15 00:00:00.00");
151 endtime = timestr2hptime ("2009/1/31 23:59:59.99");
152 ms_addselect (&selections, "IU_ANMO_00_LH?_?", starttime, endtime);
153 while ( (retcode = ms_readmsr (&msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
155 {
156 /* Print details if data record matches selection criteria */
157 if ( msr_matchselect (selections, msr, NULL) )
158 {
159 msr_print (msr, verbose);
160 }
161 }
162 if ( retcode != MS_ENDOFFILE )
164 ms_log (2, "Error reading input file %s: %s\n",
165 filename, ms_errorstr(retcode));
166 /* Cleanup memory and close file */
168 ms_readmsr (&msr, NULL, 0, NULL, NULL, 0, 0, verbose);
169 } /* End of main() */
170 The following two calls are equivalent:
172 ms_addselect (&selections, "IU_ANMO_00_LH?_?", starttime, endtime);
173 ms_addselect_comp (&selections, "IU", "ANMO", "00", "LH?", "?", startime, endtime);
174 As a further convienence usage of ms_readselectionsfile() would allow
176 the selections to be specified in a simple ASCII file and avoid the
177 need to directly call ms_addselect().
178
181 msr_srcname(3) and mst_srcname(3).
182
185 Chad Trabant
186 IRIS Data Management Center
187Libmseed API 2012/12/28 MS_SELECTION(3)