Record List

Functionality to build a list of records that contribute to a MS3TraceSeg. More...

Data Structures
struct	MS3RecordPtr
	A miniSEED record pointer and metadata. More...
struct	MS3RecordList
	Record list, holds MS3RecordPtr entries that contribute to a given MS3TraceSeg. More...

Detailed Description

Functionality to build a list of records that contribute to a MS3TraceSeg.

As a Trace List is constructed from data records, a list of the records that contribute to each segment can be built by using the MSF_RECORDLIST flag to mstl3_readbuffer() and ms3_readtracelist(). Alternatively, a record list can be built by adding records to a Trace List using mstl3_addmsr_recordptr(). Extra headers are copied into each MS3RecordPtr by default; set MSF_RECORDLIST_NOEXTRAS to omit them, usually to reduce memory usage.

The main purpose of this functionality is to support an efficient, 2-pass pattern of first reading a summary of data followed by unpacking the samples. The unpacking can be performed selectively on desired segments and optionally placed in a caller-supplied buffer.

The mstl3_unpack_recordlist() function allows for the unpacking of data samples for a given MS3TraceSeg into a caller-specified buffer, or allocating the buffer if needed.

See also

mstl3_readbuffer()

mstl3_readbuffer_selection()

ms3_readtracelist()

ms3_readtracelist_selection()

mstl3_unpack_recordlist()

mstl3_addmsr_recordptr()

---

Data Structure Documentation

MS3RecordPtr

struct MS3RecordPtr

A miniSEED record pointer and metadata.

Used to construct a list of data records that contributed to a trace segment.

The location of the record is identified at a memory address (bufferptr), the location in an open file (fileptr and fileoffset), or the location in a file (filename and fileoffset).

The filename field is a pointer to the original file name passed to the library, not a copy. The caller is responsible for ensuring that the file name remains valid for the lifetime of the record list.

A MS3Record is stored with and contains the bit flags, extra headers, etc. for the record. The raw record pointer (MS3Record.record) is only populated when the record remains available in a caller-supplied buffer; it is NULL otherwise, for example for records read from files.

The dataoffset to the encoded data is stored to enable direct decoding of data samples without re-parsing the header, used by mstl3_unpack_recordlist().

Note: the list is stored in the time order that the entries contributed to the segment.

See also

mstl3_unpack_recordlist()

Data Fields
const char *	bufferptr	Pointer in buffer to record, NULL if not used.
FILE *	fileptr	Pointer to open FILE containing record, NULL if not used.
const char *	filename	Pointer (borrowed) to file name containing record, NULL if not used.
int64_t	fileoffset	Offset into file to record for fileptr or filename.
MS3Record *	msr	Pointer to MS3Record for this record, msr->record is only valid if from a caller-supplied buffer.
nstime_t	endtime	End time of record, time of last sample.
uint32_t	dataoffset	Offset from start of record to encoded data.
void *	prvtptr	Private pointer, will not be populated by library but will be free'd.
struct MS3RecordPtr *	next	Pointer to next entry, NULL if the last.

MS3RecordList

struct MS3RecordList

Record list, holds MS3RecordPtr entries that contribute to a given MS3TraceSeg.

Data Fields
uint64_t	recordcnt	Count of records in the list (for convenience).
MS3RecordPtr *	first	Pointer to first entry, NULL if the none.
MS3RecordPtr *	last	Pointer to last entry, NULL if the none.