| MS_READMSR(3) | Library Functions Manual | MS_READMSR(3) |
ms_readmsr - Read Mini-SEED data from files
#include <libmseed.h>
int ms_readmsr ( MSRecord **ppmsr, char *msfile, int reclen,
off_t *fpos, int *last, flag skipnotdata,
flag dataflag,flag verbose );
int ms_readmsr_r ( MSFileParam **ppmsfp, MSRecord **ppmsr, char *msfile,
int reclen, off_t *fpos, int *last,
flag skipnotdata, flag dataflag,flag verbose );
int ms_readtraces ( MSTraceGroup **ppmstg, char *msfile, int reclen,
double timetol, double sampratetol,
flag dataquality, flag skipnotdata,
flag dataflag, flag verbose );
int ms_readtraces_timewin ( MSTraceGroup **ppmstg, char *msfile,
int reclen, double timetol, double sampratetol,
hptime_t starttime, hptime_t endtime,
flag dataquality, flag skipnotdata,
flag dataflag, flag verbose );
int ms_readtraces_selection ( MSTraceGroup **ppmstg, char *msfile,
int reclen, double timetol, double sampratetol,
Selections *selections, flag dataquality,
flag skipnotdata, flag dataflag, flag verbose );
int ms_readtracelist ( MSTraceList **ppmstl, char *msfile, int reclen,
double timetol, double sampratetol,
flag dataquality, flag skipnotdata,
flag dataflag, flag verbose );
int ms_readtracelist_timewin ( MSTraceList **ppmstl, char *msfile,
int reclen, double timetol, double sampratetol,
hptime_t starttime, hptime_t endtime,
flag dataquality, flag skipnotdata,
flag dataflag, flag verbose );
int ms_readtracelist_selection ( MSTraceList **ppmstl, char *msfile,
int reclen, double timetol, double sampratetol,
Selections *selections, flag dataquality,
flag skipnotdata, flag dataflag, flag verbose );
Both ms_readmsr and ms_readmsr_r will open and read, with subsequent calls, all Mini-SEED records from a specified file. Standard input will be opened if msfile is "-" (dash). As each record is read it is unpacked using msr_unpack(3). If the MSRecord struct at *ppmsr has not been initialized it must be set to NULL and it will be initialize it automatically.
The ms_readmsr version is not thread safe. The reentrant ms_readmsr_r version is thread safe and can be used to read more than one file in parallel. ms_readmsr_r stores all static file reading parameters in a MSFileParam struct. A pointer to this struct must be supplied by the caller (ppmsfp), memory will be allocated on the initial call if the pointer is NULL.
If reclen is 0 or negative the length of every record is automatically detected. For auto length detection records are first searched for a Blockette 1000 and if none is found a search is conducted for the next valid record header (the existence of the next record or end-of-file implying the length of the current record).
If the fpos pointer is not NULL the value will be set to the file position (offset from the beginning in bytes) from where the returned record was read. As a special case, if fpos is not NULL and the value it points to is less than zero it will be interpreted as the (positive) offset in the file at which to begin reading data; this feature does not work with packed files.
If the last pointer is not NULL the value will be set to 1 when the record at the end of the file is being returned, otherwise it will be 0. This indicator will not be set when the last valid record in the file is followed by padding.
If the skipnotdata flag is true (not 0) any data chunks read that do not have valid data record indicators (i.e. D, R, or Q) will be skipped.
The dataflag argument is passed directly to msr_unpack(3) and controls whether data samples are unpacked.
After reading all the input records the controlling program should call it one last time with msfile set to NULL. This will close the file and cleanup allocated memory.
If ms_readmsr or ms_readmsr_r are called with a different file than the one they currently have open they will close the currently open file, open the new file and print an error message. Properly coded applications should reset the function when the end of file has been reached as described above and not rely on this behavior.
The ms_readtraces and ms_readtracelist routines read all Mini-SEED records from a file using ms_readmsr_r and adds each one to either a MSTraceGroup or MSTraceList using mst_addmsrtogroup(3) and mstl_addmsr(3) respectively. The msfile, reclen, skipnotdata and dataflag arguments are passed directly to ms_readmsr_r. The timetol, sampratetol and dataquality arguments are passed directly to mst_addmsrtogroup(3) or mstl_addmsr(3). If the pointer to the MSTraceGroup or MSTraceList struct has not been initialized it must be set to NULL and it will be initialize automatically. The MSTraceGroup or MSTraceList structures may already contain entries and will be added to by these routines. These routines are thread safe.
The ms_readtraces_timewin and ms_readtracelist_timewin routines perform the same function as ms_readtraces and ms_readtracelist but will limit the data to records containing samples between the specified starttime and endtime.
The ms_readtraces_selection and ms_readtracelist_selection routines perform the same function as ms_readtraces and ms_readtracelist but will limit the data to records that match the specified selections. Selections include criteria for source name and time window parameters, see ms_selection(3) for more information.
On the successful read and parsing of a record ms_readmsr and ms_readmsr_r return MS_NOERROR and populate the MSRecord struct at *ppmsr. Upon reaching the end of the input file these routines return MS_ENDOFFILE. On error these routines return a libmseed error code (defined in libmseed.h)
On the successful read and parsing of a file ms_readtraces and ms_readtracelist return MS_NOERROR and populate the MSTraceGroup or MSTraceList struct. On error these routines return a libmseed error code (defined in libmseed.h)
ms_readmsr, ms_readtraces and ms_readtracelist will read packed Mini-SEED files. Packed Mini-SEED is the indexed archive format used internally at the IRIS Data Management Center and probably not used anywhere else.
Skeleton code for reading a file with ms_readmsr(3):
main() {
MSRecord *msr = NULL;
int retcode;
while ( (retcode = ms_readmsr (&msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
{
/* Do something with the record here, e.g. print */
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);
}
For reading a file with the thread safe ms_readmsr_r(3):
main() {
MSRecord *msr = NULL;
MSFileParam *msfp = NULL;
int retcode;
while ( (retcode = ms_readmsr_r (&msfp, &msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
{
/* Do something with the record here, e.g. print */
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_r (&msfp, &msr, NULL, 0, NULL, NULL, 0, 0, verbose);
}
For reading a file with ms_readtraces(3):
main() {
MSTraceList *mstl = NULL;
int retcode;
retcode = ms_readtracelist (&mstl, filename, 0, -1.0, -1.0, 0, 1, 0, verbose);
if ( retcode != MS_NOERROR )
ms_log (2, "Error reading input file %s: %s\n", filename, ms_errorstr(retcode));
retcode = ms_readtracelist (&mstl, filename2, 0, -1.0, -1.0, 0, 1, 0, verbose);
if ( retcode != MS_NOERROR )
ms_log (2, "Error reading input file %s: %s\n", filename2, ms_errorstr(retcode));
if ( ! mstl )
{
ms_log (2, "Error reading file\n");
return -1;
}
/* Do something with the traces here, e.g. print */
mstl_printtracelist (mstl, 0, verbose, 0);
mstl_free (&mstl);
}
ms_intro(3), msr_unpack(3), mst_addmsrtogroup(3), mstl_addmsr(3), ms_log(3) and ms_errorstr(3).
Chad Trabant IRIS Data Management Center
| 2011/01/06 | Libmseed API |