1MS_READMSR(3) Library Functions Manual MS_READMSR(3)
2
6 ms_readmsr - Read Mini-SEED data from files
7
10 #include <libmseed.h>
11 int ms_readmsr ( MSRecord **ppmsr, char *msfile, int reclen,
13 off_t *fpos, int *last, flag skipnotdata,
14 flag dataflag,flag verbose );
15 int ms_readmsr_r ( MSFileParam **ppmsfp, MSRecord **ppmsr, char *msfile,
17 int reclen, off_t *fpos, int *last,
18 flag skipnotdata, flag dataflag,flag verbose );
19 int ms_readtraces ( MSTraceGroup **ppmstg, char *msfile, int reclen,
21 double timetol, double sampratetol,
22 flag dataquality, flag skipnotdata,
23 flag dataflag, flag verbose );
24 int ms_readtraces_timewin ( MSTraceGroup **ppmstg, char *msfile,
26 int reclen, double timetol, double sampratetol,
27 hptime_t starttime, hptime_t endtime,
28 flag dataquality, flag skipnotdata,
29 flag dataflag, flag verbose );
30 int ms_readtraces_selection ( MSTraceGroup **ppmstg, char *msfile,
32 int reclen, double timetol, double sampratetol,
33 Selections *selections, flag dataquality,
34 flag skipnotdata, flag dataflag, flag verbose );
35 int ms_readtracelist ( MSTraceList **ppmstl, char *msfile, int reclen,
37 double timetol, double sampratetol,
38 flag dataquality, flag skipnotdata,
39 flag dataflag, flag verbose );
40 int ms_readtracelist_timewin ( MSTraceList **ppmstl, char *msfile,
42 int reclen, double timetol, double sampratetol,
43 hptime_t starttime, hptime_t endtime,
44 flag dataquality, flag skipnotdata,
45 flag dataflag, flag verbose );
46 int ms_readtracelist_selection ( MSTraceList **ppmstl, char *msfile,
48 int reclen, double timetol, double sampratetol,
49 Selections *selections, flag dataquality,
50 flag skipnotdata, flag dataflag, flag verbose );
51
54 Both ms_readmsr and ms_readmsr_r will open and read, with subsequent
55 calls, all Mini-SEED records from a specified file. Standard input
56 will be opened if msfile is "-" (dash). As each record is read it is
57 unpacked using msr_unpack(3). If the MSRecord struct at *ppmsr has not
58 been initialized it must be set to NULL and it will be initialize it
59 automatically.
60 The ms_readmsr version is not thread safe. The reentrant ms_readmsr_r
62 version is thread safe and can be used to read more than one file in
63 parallel. ms_readmsr_r stores all static file reading parameters in a
64 MSFileParam struct. A pointer to this struct must be supplied by the
65 caller (ppmsfp), memory will be allocated on the initial call if the
66 pointer is NULL.
67 If reclen is 0 or negative the length of every record is automatically
69 detected. For auto length detection records are first searched for a
70 Blockette 1000 and if none is found a search is conducted for the next
71 valid record header (the existence of the next record or end-of-file
72 implying the length of the current record).
73 If the fpos pointer is not NULL the value will be set to the file posi‐
75 tion (offset from the beginning in bytes) from where the returned
76 record was read. As a special case, if fpos is not NULL and the value
77 it points to is less than zero it will be interpreted as the (positive)
78 offset in the file at which to begin reading data; this feature does
79 not work with packed files.
80 If the last pointer is not NULL the value will be set to 1 when the
82 record at the end of the file is being returned, otherwise it will be
83 0. This indicator will not be set when the last valid record in the
84 file is followed by padding.
85 If the skipnotdata flag is true (not 0) any data chunks read that do
87 not have valid data record indicators (i.e. D, R, or Q) will be
88 skipped.
89 The dataflag argument is passed directly to msr_unpack(3) and controls
91 whether data samples are unpacked.
92 After reading all the input records the controlling program should call
94 it one last time with msfile set to NULL. This will close the file and
95 cleanup allocated memory.
96 If ms_readmsr or ms_readmsr_r are called with a different file than the
98 one they currently have open they will close the currently open file,
99 open the new file and print an error message. Properly coded applica‐
100 tions should reset the function when the end of file has been reached
101 as described above and not rely on this behavior.
102 The ms_readtraces and ms_readtracelist routines read all Mini-SEED
104 records from a file using ms_readmsr_r and adds each one to either a
105 MSTraceGroup or MSTraceList using mst_addmsrtogroup(3) and
106 mstl_addmsr(3) respectively. The msfile, reclen, skipnotdata and
107 dataflag arguments are passed directly to ms_readmsr_r. The timetol,
108 sampratetol and dataquality arguments are passed directly to mst_addm‐
109 srtogroup(3) or mstl_addmsr(3). If the pointer to the MSTraceGroup or
110 MSTraceList struct has not been initialized it must be set to NULL and
111 it will be initialize automatically. The MSTraceGroup or MSTraceList
112 structures may already contain entries and will be added to by these
113 routines. These routines are thread safe.
114 The ms_readtraces_timewin and ms_readtracelist_timewin routines perform
116 the same function as ms_readtraces and ms_readtracelist but will limit
117 the data to records containing samples between the specified starttime
118 and endtime.
119 The ms_readtraces_selection and ms_readtracelist_selection routines
121 perform the same function as ms_readtraces and ms_readtracelist but
122 will limit the data to records that match the specified selections.
123 Selections include criteria for source name and time window parameters,
124 see ms_selection(3) for more information.
125
128 On the sucessful read and parsing of a record ms_readmsr and
129 ms_readmsr_r return MS_NOERROR and populate the MSRecord struct at
130 *ppmsr. Upon reaching the end of the input file these routines return
131 MS_ENDOFFILE. On error these routines return a libmseed error code
132 (defined in libmseed.h)
133 On the sucessful read and parsing of a file ms_readtraces and ms_read‐
135 tracelist return MS_NOERROR and populate the MSTraceGroup or
136 MSTraceList struct. On error these routines return a libmseed error
137 code (defined in libmseed.h)
138
141 ms_readmsr, ms_readtraces and ms_readtracelist will read packed Mini-
142 SEED files. Packed Mini-SEED is the indexed archive format used inter‐
143 nally at the IRIS Data Management Center and probably not used anywhere
144 else.
145
148 Skeleton code for reading a file with ms_readmsr(3):
149 main() {
151 MSRecord *msr = NULL;
152 int retcode;
153 while ( (retcode = ms_readmsr (&msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
155 {
156 /* Do something with the record here, e.g. print */
157 msr_print (msr, verbose);
158 }
159 if ( retcode != MS_ENDOFFILE )
161 ms_log (2, "Error reading input file %s: %s\n", filename, ms_errorstr(retcode));
162 /* Cleanup memory and close file */
164 ms_readmsr (&msr, NULL, 0, NULL, NULL, 0, 0, verbose);
165 }
166 For reading a file with the thread safe ms_readmsr_r(3):
168 main() {
170 MSRecord *msr = NULL;
171 MSFileParam *msfp = NULL;
172 int retcode;
173 while ( (retcode = ms_readmsr_r (&msfp, &msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
175 {
176 /* Do something with the record here, e.g. print */
177 msr_print (msr, verbose);
178 }
179 if ( retcode != MS_ENDOFFILE )
181 ms_log (2, "Error reading input file %s: %s\n", filename, ms_errorstr(retcode));
182 /* Cleanup memory and close file */
184 ms_readmsr_r (&msfp, &msr, NULL, 0, NULL, NULL, 0, 0, verbose);
185 }
186 For reading a file with ms_readtraces(3):
188 main() {
190 MSTraceList *mstl = NULL;
191 int retcode;
192 retcode = ms_readtracelist (&mstl, filename, 0, -1.0, -1.0, 0, 1, 0, verbose);
194 if ( retcode != MS_NOERROR )
196 ms_log (2, "Error reading input file %s: %s\n", filename, ms_errorstr(retcode));
197 retcode = ms_readtracelist (&mstl, filename2, 0, -1.0, -1.0, 0, 1, 0, verbose);
199 if ( retcode != MS_NOERROR )
201 ms_log (2, "Error reading input file %s: %s\n", filename2, ms_errorstr(retcode));
202 if ( ! mstl )
204 {
205 ms_log (2, "Error reading file\n");
206 return -1;
207 }
208 /* Do something with the traces here, e.g. print */
210 mstl_printtracelist (mstl, 0, verbose, 0);
211 mstl_free (&mstl);
213 }
214
217 ms_intro(3), msr_unpack(3), mst_addmsrtogroup(3), mstl_addmsr(3),
218 ms_log(3) and ms_errorstr(3).
219
222 Chad Trabant
223 IRIS Data Management Center
224Libmseed API 2011/01/06 MS_READMSR(3)