1MSR_PARSE(3)               Library Functions Manual               MSR_PARSE(3)
2
3
4

NAME

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

SYNOPSIS

10       #include <libmseed.h>
11
12       int  msr_parse ( char *record, int recbuflen, MSRecord **ppmsr,
13                        int reclen, flag dataflag, flag verbose );
14
15       int  msr_parse_selection ( char *recbuf, int recbuflen,
16                                  int64_t *offset, MSRecord **ppmsr,
17                                  int reclen, Selections *selections,
18                                  flag dataflag, flag verbose );
19
20       int  ms_detect ( const char *record, int recbuflen );
21
22

DESCRIPTION

24       msr_parse will parse a SEED data record from the record buffer and pop‐
25       ulate the MSRecord structure at ppmsr, allocating one if  needed.   The
26       recbuflen  argument  is  the length of the record buffer.  Records must
27       begin at the start of the buffer.
28
29       If reclen is 0 or negative the length of record is automatically deter‐
30       mined,  otherwise reclen should be the correct record length.  For auto
31       detection of record length the record should include a  1000  blockette
32       or be followed by another record header in the buffer.
33
34       If  dataflag  is true (non-zero) the data samples will be unpacked when
35       parsing the record.  This argument is passed directly to msr_unpack(3).
36
37       msr_parse_selection will parse the first  SEED  data  record  from  the
38       recbuf  buffer  that matches the optional selections.  The offset value
39       indicates where  to  start  searching  the  buffer.   On  success,  the
40       MSRecord  structure  at ppmsr is populated and the offset to the record
41       in the buffer is set.  See the example below  for  the  intended  usage
42       pattern.
43
44       ms_detect determines whether the supplied record buffer contains a SEED
45       data record by verifying known signatures, if a  record  is  found  the
46       record length is determined by:
47
48       1) Searching the buffer up to recbuflen for a Blockette 1000.
49
50       2)  If  no Blockette 1000 is found search at MINRECLEN-byte offsets for
51       the fixed section of the next header in the  buffer,  thereby  implying
52       the record length.
53
54

RETURN VALUES

56       msr_parse returns values:
57         0 : On success and populates the supplied MSRecord.
58        >0 : Data record was detected but not enough data is present in buffer,
59             the value returned is a hint of how much more data is needed.
60        <0 : On error a negative libmseed error value is returned.
61
62       ms_detect returns values:
63        -1 : Data record not detected or error
64         0 : Data record detected but could not determine length
65        >0 : Length of the data record in bytes
66
67

EXAMPLE USAGE OF MS_PARSE_SELECTION()

69       The  ms_parse_selection() routine uses the initial setting of offset as
70       the starting point to search the buffer.  On successful  parsing  of  a
71       miniSEED record the value of offset will be the offset in the buffer to
72       the record parsed.
73
74       To properly parse all records matching specificed selection criteria, a
75       caller  must check and manage the value of offset.  In particular, when
76       the end of the buffer  is  reached  a  value  of  MS_GENERROR  will  be
77       returned  and the caller should check if the offset is still within the
78       buffer length to determine if this is a parsing error or simply the end
79       of the buffer.
80
81       The following example illustrates the intended usage:
82
83         char *recbuf = <memory buffer containing records>;
84         int64_t recbuflen = <length of buffer>;
85         int64_t offset = 0;
86         MSRecord *msr = NULL;
87         int reclen = -1;
88         Selections *selections = NULL;
89         flag dataflag = 1;
90         flag verbose = 0;
91
92         // You probaby want to set Selections
93         // For example with a call to ms_readselectionsfile (&selections, selectfile)
94
95         /* Loop over all selected records in recbuf */
96         while ( offset < recbuflen )
97           {
98             if ( msr_parse_selection (recbuf, recbuflen, &offset, &msr, reclen, selections, dataflag, verbose) )
99               {
100                 /* Only print error if offset is still within buffer length */
101                 if ( verbose && offset < recbuflen )
102                 ms_log (2, "Error parsing record at offset %"PRId64"0, offset);
103               }
104             else /* Successfully found and parsed record */
105               {
106                 /* Do something with the record, for example print the details */
107                 msr_print (msr, verbose);
108
109                 /* Increment offset in buffer for subsequent call to msr_parse_selection() */
110                 offset += msr->reclen;
111               }
112           }
113
114         /* Clean up */
115         msr_free (&msr);
116
117         if ( selections )
118           ms_freeselections (selections);
119
120

SEE ALSO

122       msr_unpack(3), ms_parse_raw(3) and ms_errorstr(3)
123
124

AUTHOR

126       Chad Trabant
127       IRIS Data Management Center
128
129
130
131Libmseed API                      2013/01/07                      MSR_PARSE(3)