Provided by: libmseed-doc_2.19.8-1_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