Ubuntu Manpage: msr_pack - Packing of Mini-SEED records.

Provided by: libmseed-doc_2.19.8-1ubuntu2_all

NAME

       msr_pack - Packing of Mini-SEED records.

SYNOPSIS

       #include <libmseed.h>

       int       msr_pack ( MSRecord *msr,
                            void (*record_handler) (char *, int, void *),
                            void *handlerdata, int64_t *packedsamples,
                            flag flush, flag verbose );

       int       msr_pack_header ( MSRecord *msr, flag normalize,
                                   flag verbose );

DESCRIPTION

msr_pack creates (packs) Mini-SEED data records. Using the record header values in a MSRecord data
structure, msr, as a template, the common header fields and blockettes are packed into a record header.
A Blockette 1000 will be added if one is not present in the template. The data samples at
MSRecord.datasamples are packed in the encoding format indicated by the MSRecord.encoding field. The
MSRecord.datasamples array and MSRecord.numsamples value will not be changed by this routine. It is the
responsibility of the calling routine to adjust the data buffer if desired. This routine will modify the
start time and sequence number of the MSRecord template as it packs records.

The key characteristics of data record & quality indicator, record length, encoding format and byte order
of packed records are taken from MSRecord.dataquality, MSRecord.reclen, MSRecord.encoding and
MSRecord.byteorder respectively. Default values for these quantities will be used when the indicator is
0 or the reclen, encoding or byteorder are -1 respectively. The default values are: dataquality = 'D',
reclen = 4096 bytes, encoding = 11 (Steim2) and byteorder = 1 (MSBF or big-endian).

MSRecord.dataquality should be either 'D', 'R', 'Q' or 'M'.

MSRecord.reclen should be set to the desired data record length in bytes which must be expressible as 2
raised to the power of X where X is between (and including) 8 to 20.

MSRecord.encoding should be set to one of the following supported Mini-SEED data encoding formats:
DE_ASCII (0), DE_INT16 (1), DE_INT32 (3), DE_FLOAT32 (4), DE_FLOAT64 (5), DE_STEIM1 (10) and DE_STEIM2
(11). The encoding aliases are defined in libmseed.h.

MSRecord.sampletype should indicated the sample type as either 'a' (ASCII), 'i' (32-bit integers), 'f'
(32-bit floats) or 'd' (64-bit doubles).

The encoding format must be appropriate for the sample type. For example, Steim compression and integer
encoding formats require integer samples and float encoding formats require the appropriate size floats
as input. As a counter example, float samples cannot be packed using Steim compression or integer
encoding formats.

MSRecord.byteorder must be either 0 (LSBF or little-endian) or 1 (MBF or big-endian).

Each time a complete record is packed it will be passed to the record_handler() function which expects
three arguments: 1) a char * to the record buffer, 2) the length of the record in bytes and 3) a void
pointer supplied by the caller. It is the responsibility of record_handler() to process the record, the
memory will be re-used or freed when record_handler() returns. This function pointer is required, there
is no other way to access the packed records.

The handlerdata pointer will be passed as the 3rd argument to record_handler(). This allows the caller
to optionally pass data directly to the record_handler().

The integer pointed to by packedsamples will be set to the total number of samples packed if not NULL.

If the flush flag is not zero all of the data will be packed into records, otherwise records will only be
packed while there are enough data samples to completely fill a record.

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

msr_pack_header packs header information, fixed section and blockettes, in a MSRecord structure into the
Mini-SEED record at MSRecord.record. This is useful for re-packing record headers after modification.
The normalize flag controls whether msr_normalize_header() is called before the header is packed.
Normalizing updates the SEED structures associated with the MSRecord with values using the MSRecord base
members (e.g. MSRecord.network, MSRecord.samplerate, etc.). Normally this should be set to true (1)
unless the associated SEED structures have been directly modified. The verbose flag controls verbosity,
a value of zero will result in no diagnostic output.

PACKING OVERRIDES

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

       Macros:
       MS_PACKHEADERBYTEORDER(X)
       MS_PACKDATABYTEORDER(X)

       Environment variables:
       PACK_HEADER_BYTEORDER
       PACK_DATA_BYTEORDER

       These  macros  and  environment variables force the byte order of the header and data respectively.  They
       could be set to either 0 (little endian) or 1 (big endian).  Normally the byte order of  the  header  and
       data  is  determined  by  the  byteorder flag of the MSRecord, this capability is included to support any
       combination of byte orders in a generalized way.

COMPRESSION HISTORY

       When the encoding format is Steim 1 or  2  compression  contiguous  records  will  be  created  including
       compression  history.  Put simply, this means that the first difference in the compression series will be
       the difference between the first sample of the current record and the last sample of the previous record.
       For the first record in a series (no previous record), a so-called cold start, the first difference  will
       be zero.

       The  compression  history can be seeded by allocating the StreamState struct for the MSRecord and setting
       the lastintsample member to the integer sample value that preceded the first sample in the current series
       and setting the comphistory flag to true (1).

RETURN VALUES

       msr_pack returns the number records created on success and -1 on error.

       msr_pack_header returns the header length in bytes on success and -1 on error.

EXAMPLE

       Skeleton code for creating (packing) Mini-SEED records with msr_pack(3):

       static void record_handler (char *record, int reclen, void *srcname) {
         if ( fwrite(record, reclen, 1, outfile) != 1 )
           {
             ms_log (2, "Error writing %s to output file0, (char *)srcname);
           }
       }

       main() {
         int64_t psamples;
         int precords;
         MSRecord *msr;
         char srcname[50];

         msr = msr_init (NULL);

         /* Populate MSRecord values */
         strcpy (msr->network, "XX");
         strcpy (msr->station, "TEST");
         strcpy (msr->channel, "BHE");
         msr->starttime = ms_seedtimestr2hptime ("2004,350,00:00:00.00");
         msr->samprate = 40.0;
         msr->reclen = 4096;         /* 4096 byte record length */
         msr->encoding = DE_STEIM2;  /* Steim 2 compression */
         msr->byteorder = 1;         /* big endian byte order */

         msr->datasamples = dataptr; /* pointer to 32-bit integer data samples */
         msr->numsamples = 1234;
         msr->sampletype = 'i';      /* declare type to be 32-bit integers */

         msr_srcname (msr, srcname, 0);

         /* Pack the record(s) */
         precords = msr_pack (msr, &record_handler, srcname, &psamples, 1, verbose);

         ms_log (0, "Packed %"PRId64" samples into %d records0,
                    psamples, precords);

         msr_free (&msr);
       }

AUTHOR

       Chad Trabant
       IRIS Data Management Center

Libmseed API                                       2013/05/17                                        MSR_PACK(3)