1MST_PACK(3) Library Functions Manual MST_PACK(3)
2
6 mst_pack - Packing of Mini-SEED records from MSTrace segments.
7
10 #include <libmseed.h>
11 int mst_pack ( MSTrace *mst,
13 void (*record_handler) (char *, int, void *),
14 void *handlerdata, int reclen, flag encoding,
15 flag byteorder, int64_t *packedsamples, flag flush,
16 flag verbose, MSRecord *mstemplate );
17 int msr_packgroup ( MSTraceGroup *mstg,
19 void (*record_handler) (char *, int, void *),
20 void *handlerdata, int reclen, flag encoding,
21 flag byteorder, int64_t *packedsamples, flag flush,
22 flag verbose, MSRecord *mstemplate );
23
26 mst_pack creates (packs) Mini-SEED data records from a MSTrace segment
27 using the specified record length (reclen), Mini-SEED encoding and
28 byteorder. Using mstemplate as a template, the common header fields
29 and blockettes are packed into a record header. If no template will be
30 used mstemplate should be set to NULL. A Blockette 1000 will be added
31 if one is not present in the template. The MSTrace.datasamples array
32 and MSTrace.numsamples value will be adjusted (reduced) as samples are
33 packed into data records. This routine will modify the record length,
34 encoding format, byte order and sequence number of the MSRecord tem‐
35 plate. The start time, sample rate, data array, number of samples and
36 sample type of the MSRecord template are preserved.
37 Default values will be used for any of the key characteristics of
39 record length, encoding format and byte order that are -1. The default
40 values are: reclen = 4096 bytes, encoding = 11 (Steim2) and byteorder =
41 1 (MSBF or big-endian).
42 reclen should be set to the desired data record length in bytes which
44 must be expressible as 2 raised to the power of X where X is between
45 (and including) 8 to 20.
46 encoding should be set to one of the following supported Mini-SEED data
48 encoding formats: DE_ASCII (0), DE_INT16 (1), DE_INT32 (3), DE_FLOAT32
49 (4), DE_FLOAT64 (5), DE_STEIM1 (10) and DE_STEIM2 (11). The encoding
50 aliases are defined in libmseed.h. MSTrace.sampletype should indicated
51 the sample type as either 'a' (ASCII), 'i' (32-bit integers), 'f'
52 (32-bit floats) or 'd' (64-bit doubles).
53 The encoding format must be appropriate for the sample type of the
55 MSTrace samples. For example, Steim compression and integer encoding
56 formats require integer samples and float encoding formats require the
57 appropriate size floats as input. As a counter example, float samples
58 cannot be packed using Steim compression or integer encoding formats.
59 byteorder must be either 0 (LSBF or little-endian) or 1 (MBF or big-
61 endian).
62 Each time a complete record is packed it will be passed to the
64 record_handler() function which expects three arguments: 1) a char * to
65 the record buffer, 2) the length of the record in bytes and 3) a void
66 pointer supplied by the caller. It is the responsibility of
67 record_handler() to process the record, the memory will be re-used or
68 freed when record_handler() returns. This function pointer is
69 required, there is no other way to access the packed records.
70 The handlerdata pointer will be passed as the 3rd argument to
72 record_handler(). This allows the caller to optionally pass data
73 directly to the record_handler().
74 The integer pointed to by packedsamples will be set to the total number
76 of samples packed.
77 If the flush flag is not zero all of the data will be packed into
79 records, otherwise records will only be packed while there are enough
80 data samples to completely fill a record.
81 The verbose flag controls verbosity, a value of zero will result in no
83 diagnostic output.
84 mst_packgroup simply calls mst_pack for each MSTrace in the specified
86 MSTraceGroup. The integer pointed to by packedsamples will be set to
87 the total number of samples packed.
88
91 When the encoding format is Steim 1 or 2 compression contiguous records
92 will be created including compression history. Put simply, this means
93 that the first difference in the compression series will be the differ‐
94 ence between the first sample of the current record and the last sample
95 of the previous record. For the first record in a series (no previous
96 record), a so-called cold start, the first difference will be zero.
97 The compression history can be seeded by allocating the StreamState
99 struct for the MSTrace and setting the lastintsample member to the
100 integer sample value that preceded the first sample in the current
101 series and setting the comphistory flag to true (1).
102
105 mst_pack returns the number records created on success and -1 on error.
106 mst_packgroup returns the total (for all MSTraces) number of record
108 created on success and -1 on error.
109
112 When using a MSRecord template (mstemplate) the dataquality member must
113 be set to a valid value. It is also advisable to set the network, sta‐
114 tion, location and channel indicators to appropriate values. Unless
115 these source indicators need to change they can simply be copied from
116 the matching MSTrace members.
117
120 Skeleton code for creating (packing) Mini-SEED records with
121 mst_pack(3):
122 static void record_handler (char *record, int reclen, void *srcname) {
124 if ( fwrite(record, reclen, 1, outfile) != 1 )
125 {
126 ms_log (2, "Error writing %s to output file0, (char *)srcname);
127 }
128 }
129 main() {
131 int64_t psamples;
132 int precords;
133 MSTrace *mst;
134 char srcname[50];
135 mst = mst_init (NULL);
137 /* Populate MSTrace values */
139 strcpy (mst->network, "XX");
140 strcpy (mst->station, "TEST");
141 strcpy (mst->channel, "BHE");
142 mst->starttime = ms_seedtimestr2hptime ("2004,350,00:00:00.000000");
143 mst->samprate = 40.0;
144 /* The datasamples pointer and numsamples counter will be adjusted by
146 the packing routine, the datasamples array must be dynamic memory
147 allocated by the malloc() family of routines. */
148 mst->datasamples = dataptr; /* pointer to 32-bit integer data samples */
149 mst->numsamples = 1234;
150 mst->sampletype = 'i'; /* declare type to be 32-bit integers */
151 mst_srcname (mst, srcname, 0);
153 /* Pack 4096 byte, big-endian records, using Steim-2 compression */
155 precords = mst_pack (mst, &record_handler, srcname, 4096, DE_STEIM2,
156 1, &psamples, 1, verbose, NULL);
157 ms_log (0, "Packed %"PRId64" samples into %d records0,
159 psamples, precords);
160 mst_free (&mst);
162 }
163
166 ms_intro(3) and msr_pack(3).
167
170 Chad Trabant
171 IRIS Data Management Center
172Libmseed API 2013/05/17 MST_PACK(3)