1MSR_PACK(3) Library Functions Manual MSR_PACK(3)
2
6 msr_pack - Packing of Mini-SEED records.
7
10 #include <libmseed.h>
11 int msr_pack ( MSRecord *msr,
13 void (*record_handler) (char *, int, void *),
14 void *handlerdata, int64_t *packedsamples,
15 flag flush, flag verbose );
16 int msr_pack_header ( MSRecord *msr, flag normalize,
18 flag verbose );
19
22 msr_pack creates (packs) Mini-SEED data records. Using the record
23 header values in a MSRecord data structure, msr, as a template, the
24 common header fields and blockettes are packed into a record header. A
25 Blockette 1000 will be added if one is not present in the template.
26 The data samples at MSRecord.datasamples are packed in the encoding
27 format indicated by the MSRecord.encoding field. The MSRecord.datasam‐
28 ples array and MSRecord.numsamples value will not be changed by this
29 routine. It is the responsibility of the calling routine to adjust the
30 data buffer if desired. This routine will modify the start time and
31 sequence number of the MSRecord template as it packs records.
32 The key characteristics of data record & quality indicator, record
34 length, encoding format and byte order of packed records are taken from
35 MSRecord.dataquality, MSRecord.reclen, MSRecord.encoding and
36 MSRecord.byteorder respectively. Default values for these quantities
37 will be used when the indicator is 0 or the reclen, encoding or byte‐
38 order are -1 respectively. The default values are: dataquality = 'D',
39 reclen = 4096 bytes, encoding = 11 (Steim2) and byteorder = 1 (MSBF or
40 big-endian).
41 MSRecord.dataquality should be either 'D', 'R', 'Q' or 'M'.
43 MSRecord.reclen should be set to the desired data record length in
45 bytes which must be expressible as 2 raised to the power of X where X
46 is between (and including) 8 to 20.
47 MSRecord.encoding should be set to one of the following supported Mini-
49 SEED data encoding formats: DE_ASCII (0), DE_INT16 (1), DE_INT32 (3),
50 DE_FLOAT32 (4), DE_FLOAT64 (5), DE_STEIM1 (10) and DE_STEIM2 (11). The
51 encoding aliases are defined in libmseed.h.
52 MSRecord.sampletype should indicated the sample type as either 'a'
54 (ASCII), 'i' (32-bit integers), 'f' (32-bit floats) or 'd' (64-bit dou‐
55 bles).
56 The encoding format must be appropriate for the sample type. For exam‐
58 ple, Steim compression and integer encoding formats require integer
59 samples and float encoding formats require the appropriate size floats
60 as input. As a counter example, float samples cannot be packed using
61 Steim compression or integer encoding formats.
62 MSRecord.byteorder must be either 0 (LSBF or little-endian) or 1 (MBF
64 or big-endian).
65 Each time a complete record is packed it will be passed to the
67 record_handler() function which expects three arguments: 1) a char * to
68 the record buffer, 2) the length of the record in bytes and 3) a void
69 pointer supplied by the caller. It is the responsibility of
70 record_handler() to process the record, the memory will be re-used or
71 freed when record_handler() returns. This function pointer is
72 required, there is no other way to access the packed records.
73 The handlerdata pointer will be passed as the 3rd argument to
75 record_handler(). This allows the caller to optionally pass data
76 directly to the record_handler().
77 The integer pointed to by packedsamples will be set to the total number
79 of samples packed if not NULL.
80 If the flush flag is not zero all of the data will be packed into
82 records, otherwise records will only be packed while there are enough
83 data samples to completely fill a record.
84 The verbose flag controls verbosity, a value of zero will result in no
86 diagnostic output.
87 msr_pack_header packs header information, fixed section and blockettes,
89 in a MSRecord structure into the Mini-SEED record at MSRecord.record.
90 This is useful for re-packing record headers after modification. The
91 normalize flag controls whether msr_normalize_header() is called before
92 the header is packed. Normalizing updates the SEED structures associ‐
93 ated with the MSRecord with values using the MSRecord base members
94 (e.g. MSRecord.network, MSRecord.samplerate, etc.). Normally this
95 should be set to true (1) unless the associated SEED structures have
96 been directly modified. The verbose flag controls verbosity, a value
97 of zero will result in no diagnostic output.
98
101 The following macros and environment variables effect the packing of
102 Mini-SEED:
103 Macros:
105 MS_PACKHEADERBYTEORDER(X)
106 MS_PACKDATABYTEORDER(X)
107 Environment variables:
109 PACK_HEADER_BYTEORDER
110 PACK_DATA_BYTEORDER
111 These macros and environment variables force the byte order of the
113 header and data respectively. They could be set to either 0 (little
114 endian) or 1 (big endian). Normally the byte order of the header and
115 data is determined by the byteorder flag of the MSRecord, this capabil‐
116 ity is included to support any combination of byte orders in a general‐
117 ized way.
118
121 When the encoding format is Steim 1 or 2 compression contiguous records
122 will be created including compression history. Put simply, this means
123 that the first difference in the compression series will be the differ‐
124 ence between the first sample of the current record and the last sample
125 of the previous record. For the first record in a series (no previous
126 record), a so-called cold start, the first difference will be zero.
127 The compression history can be seeded by allocating the StreamState
129 struct for the MSRecord and setting the lastintsample member to the
130 integer sample value that preceded the first sample in the current
131 series and setting the comphistory flag to true (1).
132
135 msr_pack returns the number records created on success and -1 on error.
136 msr_pack_header returns the header length in bytes on success and -1 on
138 error.
139
142 Skeleton code for creating (packing) Mini-SEED records with
143 msr_pack(3):
144 static void record_handler (char *record, int reclen, void *srcname) {
146 if ( fwrite(record, reclen, 1, outfile) != 1 )
147 {
148 ms_log (2, "Error writing %s to output file0, (char *)srcname);
149 }
150 }
151 main() {
153 int64_t psamples;
154 int precords;
155 MSRecord *msr;
156 char srcname[50];
157 msr = msr_init (NULL);
159 /* Populate MSRecord values */
161 strcpy (msr->network, "XX");
162 strcpy (msr->station, "TEST");
163 strcpy (msr->channel, "BHE");
164 msr->starttime = ms_seedtimestr2hptime ("2004,350,00:00:00.00");
165 msr->samprate = 40.0;
166 msr->reclen = 4096; /* 4096 byte record length */
167 msr->encoding = DE_STEIM2; /* Steim 2 compression */
168 msr->byteorder = 1; /* big endian byte order */
169 msr->datasamples = dataptr; /* pointer to 32-bit integer data samples */
171 msr->numsamples = 1234;
172 msr->sampletype = 'i'; /* declare type to be 32-bit integers */
173 msr_srcname (msr, srcname, 0);
175 /* Pack the record(s) */
177 precords = msr_pack (msr, &record_handler, srcname, &psamples, 1, verbose);
178 ms_log (0, "Packed %"PRId64" samples into %d records0,
180 psamples, precords);
181 msr_free (&msr);
183 }
184
187 ms_intro(3), mst_pack(3), mst_packgroup(3), msr_normalize_header(3) and
188 msr_unpack(3).
189
192 Chad Trabant
193 IRIS Data Management Center
194Libmseed API 2013/05/17 MSR_PACK(3)