MST_PACK(3)

💖 MST_PACK(3) — the libmseed girlies' guide 💖

okay bestie, listen up. this is mst_pack from the Library Functions Manual, and she is that girl: the one who takes your MSTrace segments and turns them into actual Mini-SEED records. 🎀 let's get into it, fr fr.

---

✨ NAME ✨

mst_pack — packing of Mini-SEED records from MSTrace segments. literally her whole job. 💅

---

🌸 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 record length you asked for (reclen), the Mini-SEED encoding, and the byteorder. iconic behaviour. ✨

using mstemplate as a template, the common header fields and blockettes get packed into a record header. if you're not using a template, set mstemplate to NULL, no drama. a Blockette 1000 gets added if one isn't already in the template. the MSTrace.datasamples array and MSTrace.numsamples value get adjusted (reduced 👀) as samples get packed into data records. this routine will modify the record length, encoding format, byte order and sequence number of the MSRecord template — but the start time, sample rate, data array, number of samples and sample type of the MSRecord template are preserved. she only touches what she has to. 🫶

---

default values get used for any of the key characteristics — record length, encoding format and byte order — that are -1. the defaults are:

• reclen = 4096 bytes
• encoding = 11 (Steim2)
• byteorder = 1 (MSBF or big-endian)

---

reclen should be set to the desired data record length in bytes, and it must be expressible as 2 raised to the power of X, where X is between (and including) 8 to 20. no in-between vibes allowed. 😭

---

encoding should be set to one of these supported Mini-SEED data encoding formats:

• DE_ASCII (0)
• DE_INT16 (1)
• DE_INT32 (3)
• DE_FLOAT32 (4)
• DE_FLOAT64 (5)
• DE_STEIM1 (10)
• DE_STEIM2 (11)

the encoding aliases are defined in libmseed.h. MSTrace.sampletype should indicate 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. it's giving mismatch energy and it will not slay. 💀

---

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

---

each time a complete record is packed, it gets 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
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. periodt. 👑

---

the handlerdata pointer gets passed as the 3rd argument to record_handler(). this lets the caller optionally pass data directly to the record_handler(). cute, right? 💜

---

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 gets packed into records. otherwise, records only get packed while there are enough data samples to completely fill a record. 🎀

---

the verbose flag controls verbosity — a value of zero results in no diagnostic output. silence, but make it intentional.

---

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. she's the group-chat admin of packing. 🌈

---

🧚 COMPRESSION HISTORY 🧚

when the encoding format is Steim 1 or 2 compression, contiguous records get created including compression history. put simply, this means 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 of records created on success, and -1 on error.
• mst_packgroup returns the total (for all MSTraces) number of records created on success, and -1 on error.

---

💀 CAVEATS 💀

when using an 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. don't skip this, bestie, it's lowkey important. 🙈

---

🔥 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). go read them too, iykyk. 💖

---

👑 AUTHOR 👑

Chad Trabant IRIS Data Management Center

---

and that's the whole page, bestie!! ✨ this libmseed API moment was documented on 2013/05/17 and it's still serving. mwah 💅💖🦋