Ubuntu Manpage: msr_unpack - Unpacking of Mini-SEED records.

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);
       }

AUTHOR

       Chad Trabant
       IRIS Data Management Center