msr_unpack(3)

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

NAME

6       msr_unpack - Unpacking of Mini-SEED records.
7
8

SYNOPSIS

10       #include <libmseed.h>
11
12       int msr_unpack ( char *record, int reclen, MSRecord **ppmsr,
13                        flag dataflag, flag verbose );
14
15       int msr_unpack_data ( MSRecord *msr, int swapflag, flag verbose );
16
17

DESCRIPTION

19       msr_unpack  will unpack a Mini-SEED data record and populate a MSRecord
20       data structure, optionally  unpacking  data  samples.   All  multi-byte
21       quantities  will  be byte-swapped to the host byte order.  The MSRecord
22       data structure is described in ms_intro(3).
23
24       The reclen parameter specifies the length of the data record pointed to
25       by record in bytes.
26
27       If  the *ppmsr pointer is NULL a new MSRecord will be allocated, if not
28       the existing MSRecord will be reinitialized and reused  destroying  any
29       previous contents.  The ppmsr pointer itself must not be NULL.
30
31       If the dataflag flag is not zero any data samples in the record will be
32       unpacked/decompressed.  The following data encoding  formats  are  sup‐
33       ported:  ASCII, INT16, INT32, FLOAT32, FLOAT64, STEIM1 and STEIM2.  The
34       MSRecord.datasamples pointer will be set appropriately and the  samples
35       will  be  either ASCII, 32-bit integers, 32-bit floats or 64-bit floats
36       with the same byte order as the host machine.  MSRecord.numsamples will
37       be   set   to  the  actual  number  of  samples  unpacked/decompressed.
38       MSRecord.sampletype will  indicated  the  sample  type  as  either  'a'
39       (ASCII), 'i' (32-bit integers), 'f' (32-bit floats) or 'd' (64-bit dou‐
40       bles).  The size of each sample  type  in  bytes  is  returned  by  the
41       get_samplesize(3) lookup routine.
42
43       The  verbose flag controls verbosity, a value of zero will result in no
44       diagnostic output.
45
46       msr_unpack_data will unpack the data  samples  for  an  already  parsed
47       MSRecord   structure   from   the  original  record  available  at  the
48       MSRecord->record pointer.  Normally this is called by  msr_unpack  when
49       the  dataflag  is not zero, but it can be useful when the program needs
50       to first unpack the header of a record and decide later if the  samples
51       are  needed.  If called independently the caller must determine if byte
52       swapping of data samples is needed.
53
54

UNPACKING OVERRIDES

56       The following macros and environment variables effect the unpacking  of
57       Mini-SEED:
58
59       Macros:
60       MS_UNPACKHEADERBYTEORDER(X)
61       MS_UNPACKDATABYTEORDER(X)
62       MS_UNPACKDATAFORMAT(X)
63       MS_UNPACKDATAFORMATFALLBACK(X)
64
65       Environment variables:
66       UNPACK_HEADER_BYTEORDER
67       UNPACK_DATA_BYTEORDER
68       UNPACK_DATA_FORMAT
69       UNPACK_DATA_FORMAT_FALLBACK
70
71       The  UNPACK_HEADER_BYTEORDER and UNPACK_DATA_BYTEORDER macros and vari‐
72       ables force the byte order of the header and data  respectively.   They
73       could  be  set  to  either  0  (little  endian) or 1 (big endian).  See
74       ms_intro(3) for a description of how libmseed determines a records byte
75       order.
76
77       The  UNPACK_DATA_FORMAT  macro and variable forces the encoding format,
78       this should be set to any of the supported formats  codes  (i.e.  10  =
79       Steim-1 compression).
80
81       The  UNPACK_DATA_FORMAT_FALLBACK macro and variable defines an encoding
82       format that will be used when the SEED data record  does  not  indicate
83       the  format,  i.e.  the  record  does not include a 1000 blockette.  By
84       default the fallback encoding format is 10 (Steim-1  compression).   If
85       this  default  is invoked and the byte order of the data is unspecified
86       big endian byte order will be assumed.   If  a  data  record  does  not
87       include  a  1000  blockette it is not Mini-SEED, the capability to read
88       these records is included only to support legacy data.
89
90

RETURN VALUE

92       On the sucessful parsing of a record msr_unpack returns MS_NOERROR  and
93       populates the MSRecord struct at *ppmsr.  On error msr_unpack returns a
94       libmseed error code (defined in libmseed.h)
95
96

EXAMPLE

98       Skeleton code for unpacking a Mini-SEED record with msr_unpack(3):
99
100       main() {
101         MSRecord *msr = NULL;
102         char *record;
103         int reclen;
104         int retcode;
105
106         record = recordptr;   /* pointer to Mini-SEED record */
107         reclen = 4096;        /* 4096 byte record length */
108
109         /* Unpack record header and data samples */
110         retcode = msr_unpack (record, reclen, &msr, 1, verbose);
111
112         if ( retcode != MS_NOERROR )
113           fprintf (stderr, "Error parsing record\n");
114         else
115           printf ("Unpacked %d samples0, msr->numsamples);
116
117         /* Print record information */
118         msr_print (msr, verbose);
119
120         msr_free (&msr);
121       }
122
123

AUTHOR

129       Chad Trabant
130       IRIS Data Management Center
131
132
133
134Libmseed API                      2012/12/22                     MSR_UNPACK(3)