plucky (3) msr_parse_selection.3.gz

NAME

       msr_parse - Detect and parse a SEED data record from a memory buffer

SYNOPSIS

       #include <libmseed.h>

       int  msr_parse ( char *record, int recbuflen, MSRecord **ppmsr,
                        int reclen, flag dataflag, flag verbose );

       int  msr_parse_selection ( char *recbuf, int recbuflen,
                                  int64_t *offset, MSRecord **ppmsr,
                                  int reclen, Selections *selections,
                                  flag dataflag, flag verbose );

       int  ms_detect ( const char *record, int recbuflen );

DESCRIPTION

       msr_parse  will  parse  a  SEED data record from the record buffer and populate the MSRecord structure at
       ppmsr, allocating one if needed.  The recbuflen argument is the length of  the  record  buffer.   Records
       must begin at the start of the buffer.

       If  reclen  is 0 or negative the length of record is automatically determined, otherwise reclen should be
       the correct record length.  For auto detection  of  record  length  the  record  should  include  a  1000
       blockette or be followed by another record header in the buffer.

       If  dataflag is true (non-zero) the data samples will be unpacked when parsing the record.  This argument
       is passed directly to msr_unpack(3).

       msr_parse_selection will parse the first SEED data  record  from  the  recbuf  buffer  that  matches  the
       optional  selections.   The  offset value indicates where to start searching the buffer.  On success, the
       MSRecord structure at ppmsr is populated and the offset to the record in the  buffer  is  set.   See  the
       example below for the intended usage pattern.

       ms_detect  determines  whether  the supplied record buffer contains a SEED data record by verifying known
       signatures, if a record is found the record length is determined by:

       1) Searching the buffer up to recbuflen for a Blockette 1000.

       2) If no Blockette 1000 is found search at MINRECLEN-byte offsets for  the  fixed  section  of  the  next
       header in the buffer, thereby implying the record length.

RETURN VALUES

       msr_parse returns values:
         0 : On success and populates the supplied MSRecord.
        >0 : Data record was detected but not enough data is present in buffer,
             the value returned is a hint of how much more data is needed.
        <0 : On error a negative libmseed error value is returned.

       ms_detect returns values:
        -1 : Data record not detected or error
         0 : Data record detected but could not determine length
        >0 : Length of the data record in bytes

EXAMPLE USAGE OF MS_PARSE_SELECTION()

       The  ms_parse_selection()  routine uses the initial setting of offset as the starting point to search the
       buffer.  On successful parsing of a miniSEED record the value of offset will be the offset in the  buffer
       to the record parsed.

       To  properly parse all records matching specificed selection criteria, a caller must check and manage the
       value of offset.  In particular, when the end of the buffer is reached a value  of  MS_GENERROR  will  be
       returned and the caller should check if the offset is still within the buffer length to determine if this
       is a parsing error or simply the end of the buffer.

       The following example illustrates the intended usage:

         char *recbuf = <memory buffer containing records>;
         int64_t recbuflen = <length of buffer>;
         int64_t offset = 0;
         MSRecord *msr = NULL;
         int reclen = -1;
         Selections *selections = NULL;
         flag dataflag = 1;
         flag verbose = 0;

         // You probaby want to set Selections
         // For example with a call to ms_readselectionsfile (&selections, selectfile)

         /* Loop over all selected records in recbuf */
         while ( offset < recbuflen )
           {
             if ( msr_parse_selection (recbuf, recbuflen, &offset, &msr, reclen, selections, dataflag, verbose) )
               {
                 /* Only print error if offset is still within buffer length */
                 if ( verbose && offset < recbuflen )
                 ms_log (2, "Error parsing record at offset %"PRId64"0, offset);
               }
             else /* Successfully found and parsed record */
               {
                 /* Do something with the record, for example print the details */
                 msr_print (msr, verbose);

                 /* Increment offset in buffer for subsequent call to msr_parse_selection() */
                 offset += msr->reclen;
               }
           }

         /* Clean up */
         msr_free (&msr);

         if ( selections )
           ms_freeselections (selections);

SEE ALSO

       msr_unpack(3), ms_parse_raw(3) and ms_errorstr(3)

AUTHOR

       Chad Trabant
       IRIS Data Management Center