NAME

       mst_pack - Packing of Mini-SEED records from MSTrace segments.

SYNOPSIS

       #include <libmseed.h>

       int  mst_pack ( MSTrace *mst,
                       void (*record_handler) (char *, int, void *),
                       void *handlerdata, int reclen, flag encoding,
                       flag byteorder, int64_t *packedsamples, flag flush,
                       flag verbose, MSRecord *mstemplate );

       int  msr_packgroup ( MSTraceGroup *mstg,
                            void (*record_handler) (char *, int, void *),
                            void *handlerdata, int reclen, flag encoding,
                            flag byteorder, int64_t *packedsamples, flag flush,
                            flag verbose, MSRecord *mstemplate );

DESCRIPTION

       mst_pack creates (packs) Mini-SEED data records from a MSTrace segment using the specified
       record length (reclen), Mini-SEED encoding and byteorder.  Using mstemplate as a template,
       the  common  header fields and blockettes are packed into a record header.  If no template
       will be used mstemplate should be set to NULL.  A Blockette 1000 will be added if  one  is
       not  present  in the template.  The MSTrace.datasamples array and MSTrace.numsamples value
       will be adjusted (reduced) as samples are packed into data  records.   This  routine  will
       modify  the record length, encoding format, byte order and sequence number of the MSRecord
       template.  The start time, sample rate, data array, number of samples and sample  type  of
       the MSRecord template are preserved.

       Default  values will be used for any of the key characteristics of record length, encoding
       format and byte order that are -1.  The default values are: reclen = 4096 bytes,  encoding
       = 11 (Steim2) and byteorder = 1 (MSBF or big-endian).

       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.

       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.   MSTrace.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 of the MSTrace  samples.   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.

       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  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.

       mst_packgroup  simply  calls mst_pack for each MSTrace in the specified MSTraceGroup.  The
       integer pointed to by packedsamples will be set to the total number of samples packed.

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 MSTrace
       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

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

       mst_packgroup returns the total (for all MSTraces) number of record created on success and
       -1 on error.

CAVEATS

       When  using a MSRecord template (mstemplate) the dataquality member must be set to a valid
       value.  It is also advisable to set the network, station, location and channel  indicators
       to  appropriate  values.  Unless these source indicators need to change they can simply be
       copied from the matching MSTrace members.

EXAMPLE

       Skeleton code for creating (packing) Mini-SEED records with mst_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;
         MSTrace *mst;
         char srcname[50];

         mst = mst_init (NULL);

         /* Populate MSTrace values */
         strcpy (mst->network, "XX");
         strcpy (mst->station, "TEST");
         strcpy (mst->channel, "BHE");
         mst->starttime = ms_seedtimestr2hptime ("2004,350,00:00:00.000000");
         mst->samprate = 40.0;

         /* The datasamples pointer and numsamples counter will be adjusted by
            the packing routine, the datasamples array must be dynamic memory
            allocated by the malloc() family of routines. */
         mst->datasamples = dataptr; /* pointer to 32-bit integer data samples */
         mst->numsamples = 1234;
         mst->sampletype = 'i';      /* declare type to be 32-bit integers */

         mst_srcname (mst, srcname, 0);

         /* Pack 4096 byte, big-endian records, using Steim-2 compression */
         precords = mst_pack (mst, &record_handler, srcname, 4096, DE_STEIM2,
                              1, &psamples, 1, verbose, NULL);

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

         mst_free (&mst);
       }

SEE ALSO

       ms_intro(3) and msr_pack(3).

AUTHOR

       Chad Trabant
       IRIS Data Management Center