NAME

       msr_unpack - Unpacking of Mini-SEED records.

SYNOPSIS

       #include <libmseed.h>

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

       int msr_unpack_data ( MSRecord *msr, int swapflag, flag verbose );

DESCRIPTION

       msr_unpack  will  unpack  a  Mini-SEED  data  record  and  populate a MSRecord data structure, optionally
       unpacking data samples.  All multi-byte quantities will be byte-swapped to  the  host  byte  order.   The
       MSRecord data structure is described in ms_intro(3).

       The reclen parameter specifies the length of the data record pointed to by record in bytes.

       If  the  *ppmsr  pointer  is  NULL a new MSRecord will be allocated, if not the existing MSRecord will be
       reinitialized and reused destroying any previous contents.  The ppmsr pointer itself must not be NULL.

       If the dataflag flag is not zero any data samples in  the  record  will  be  unpacked/decompressed.   The
       following  data encoding formats are supported: ASCII, INT16, INT32, FLOAT32, FLOAT64, STEIM1 and STEIM2.
       The MSRecord.datasamples pointer will be set appropriately and the samples will be either  ASCII,  32-bit
       integers,   32-bit   floats   or   64-bit   floats  with  the  same  byte  order  as  the  host  machine.
       MSRecord.numsamples  will   be   set   to   the   actual   number   of   samples   unpacked/decompressed.
       MSRecord.sampletype  will  indicated  the  sample  type as either 'a' (ASCII), 'i' (32-bit integers), 'f'
       (32-bit floats) or 'd' (64-bit doubles).  The size of each sample  type  in  bytes  is  returned  by  the
       get_samplesize(3) lookup routine.

       The verbose flag controls verbosity, a value of zero will result in no diagnostic output.

       msr_unpack_data  will  unpack the data samples for an already parsed MSRecord structure from the original
       record available at the MSRecord->record pointer.   Normally  this  is  called  by  msr_unpack  when  the
       dataflag  is not zero, but it can be useful when the program needs to first unpack the header of a record
       and decide later if the samples are needed.  If called independently the caller must  determine  if  byte
       swapping of data samples is needed.

UNPACKING OVERRIDES

       The following macros and environment variables effect the unpacking of Mini-SEED:

       Macros:
       MS_UNPACKHEADERBYTEORDER(X)
       MS_UNPACKDATABYTEORDER(X)
       MS_UNPACKDATAFORMAT(X)
       MS_UNPACKDATAFORMATFALLBACK(X)

       Environment variables:
       UNPACK_HEADER_BYTEORDER
       UNPACK_DATA_BYTEORDER
       UNPACK_DATA_FORMAT
       UNPACK_DATA_FORMAT_FALLBACK

       The  UNPACK_HEADER_BYTEORDER  and  UNPACK_DATA_BYTEORDER macros and variables force the byte order of the
       header and data respectively.  They could be set to either 0 (little endian)  or  1  (big  endian).   See
       ms_intro(3) for a description of how libmseed determines a records byte order.

       The  UNPACK_DATA_FORMAT  macro  and variable forces the encoding format, this should be set to any of the
       supported formats codes (i.e. 10 = Steim-1 compression).

       The UNPACK_DATA_FORMAT_FALLBACK macro and variable defines an encoding format that will be used when  the
       SEED  data  record  does  not indicate the format, i.e. the record does not include a 1000 blockette.  By
       default the fallback encoding format is 10 (Steim-1 compression).  If this default  is  invoked  and  the
       byte  order  of the data is unspecified big endian byte order will be assumed.  If a data record does not
       include a 1000 blockette it is not Mini-SEED, the capability to read these records is  included  only  to
       support legacy data.

RETURN VALUE

       On  the successful parsing of a record msr_unpack returns MS_NOERROR and populates the MSRecord struct at
       *ppmsr.  On error msr_unpack returns a libmseed error code (defined in libmseed.h)

EXAMPLE

       Skeleton code for unpacking a Mini-SEED record with msr_unpack(3):

       main() {
         MSRecord *msr = NULL;
         char *record;
         int reclen;
         int retcode;

         record = recordptr;   /* pointer to Mini-SEED record */
         reclen = 4096;        /* 4096 byte record length */

         /* Unpack record header and data samples */
         retcode = msr_unpack (record, reclen, &msr, 1, verbose);

         if ( retcode != MS_NOERROR )
           fprintf (stderr, "Error parsing record\n");
         else
           printf ("Unpacked %d samples0, msr->numsamples);

         /* Print record information */
         msr_print (msr, verbose);

         msr_free (&msr);
       }

SEE ALSO

       ms_intro(3), msr_pack(3) and msr_print(3).

AUTHOR

       Chad Trabant
       IRIS Data Management Center

Libmseed API                                       2012/12/22                                      MSR_UNPACK(3)