Provided by: libmseed-doc_2.19.8-1_all bug

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