Provided by: libmseed-doc_2.19.8-1ubuntu2_all 
NAME
ms_readmsr - Read Mini-SEED data from files
SYNOPSIS
#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 );
DESCRIPTION
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.
RETURN VALUES
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)
PACKED FILES
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.
EXAMPLE
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);
}
SEE ALSO
ms_intro(3), msr_unpack(3), mst_addmsrtogroup(3), mstl_addmsr(3), ms_log(3) and ms_errorstr(3).
AUTHOR
Chad Trabant
IRIS Data Management Center
Libmseed API 2011/01/06 MS_READMSR(3)