msr_unpack - Man Page

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

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.

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.

On the sucessful 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)

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

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

Chad Trabant
IRIS Data Management Center

ms_find_reclen(3), ms_intro(3), msr_addblockette(3), ms_readmsr(3), msr_host_latency(3), msr_init(3), msr_pack(3), msr_parse(3), msr_print(3), msr_samprate(3), msr_starttime(3).