Data selections to be used as filters. More...

Data Structures
struct	MS3SelectTime
	Data selection structure time window definition containers. More...

struct	MS3Selections
	Data selection structure definition containers. More...

Functions
const MS3Selections *	ms3_matchselect (const MS3Selections selections, const char sid, nstime_t starttime, nstime_t endtime, int pubversion, const MS3SelectTime **ppselecttime)
	Test the specified parameters for a matching selection entry.

const MS3Selections *	msr3_matchselect (const MS3Selections selections, const MS3Record msr, const MS3SelectTime **ppselecttime)
	Test the MS3Record for a matching selection entry.

int	ms3_addselect (MS3Selections *ppselections, const char sidpattern, nstime_t starttime, nstime_t endtime, uint8_t pubversion)
	Add selection parameters to selection list.

int	ms3_addselect_comp (MS3Selections *ppselections, char network, char station, char location, char *channel, nstime_t starttime, nstime_t endtime, uint8_t pubversion)
	Add selection parameters to a selection list based on separate source name codes.

int	ms3_readselectionsfile (MS3Selections *ppselections, const char filename)
	Read data selections from a file.

void	ms3_freeselections (MS3Selections *selections)
	Free all memory associated with a MS3Selections.

void	ms3_printselections (const MS3Selections *selections)
	Print the selections list using the ms_log() facility.

Detailed Description

Data selections to be used as filters.

Selections are the identification of data, by source identifier and time ranges, that are desired. Capability is included to read selections from files and to match data against a selection list.

For data to be selected it must only match one of the selection entries. In other words, multiple selection entries are treated with OR logic.

The ms3_readmsr_selection() and ms3_readtracelist_selection() routines accept MS3Selections and allow selective (and efficient) reading of data from files.

Data Structure Documentation

◆ MS3SelectTime

struct MS3SelectTime

Data selection structure time window definition containers.

Data Fields
nstime_t	starttime	Earliest data for matching channels, use NSTUNSET for open.
nstime_t	endtime	Latest data for matching channels, use NSTUNSET for open.
struct MS3SelectTime *	next	Pointer to next selection time, NULL if the last.

◆ MS3Selections

struct MS3Selections

Data selection structure definition containers.

Data Fields
char	sidpattern[100]	Matching (globbing) pattern for source ID.
struct MS3SelectTime *	timewindows	Pointer to time window list for this source ID.
struct MS3Selections *	next	Pointer to next selection, NULL if the last.
uint8_t	pubversion	Selected publication version, use 0 for any.

Function Documentation

◆ ms3_matchselect()

const MS3Selections * ms3_matchselect	(	const MS3Selections *	selections,
		const char *	sid,
		nstime_t	starttime,
		nstime_t	endtime,
		int	pubversion,
		const MS3SelectTime **	ppselecttime )

extern

Test the specified parameters for a matching selection entry.

Search the MS3Selections for an entry matching the provided parameters. The MS3Selections.sidpattern may contain globbing characters. The MS3Selections.timewindows many contain start and end times set to NSTUNSET to denote "open" times.

Positive matching requires:

glob match of sid against sidpattern in selection
time window intersection with range in selection
equal pubversion if selection pubversion > 0

Parameters

[in]	selections	MS3Selections to search
[in]	sid	Source ID to match
[in]	starttime	Start time to match
[in]	endtime	End time to match
[in]	pubversion	Publication version to match
[out]	ppselecttime	Pointer-to-pointer to return the matching MS3SelectTime entry

Returns: A pointer to matching MS3Selections entry successful match and NULL for no match or error.

◆ msr3_matchselect()

const MS3Selections * msr3_matchselect	(	const MS3Selections *	selections,
		const MS3Record *	msr,
		const MS3SelectTime **	ppselecttime )

extern

Test the MS3Record for a matching selection entry.

Search the MS3Selections for an entry matching the provided parameters.

Positive matching requires:

glob match of sid against sidpattern in selection
time window intersection with range in selection
equal pubversion if selection pubversion > 0

Parameters

[in]	selections	MS3Selections to search
[in]	msr	MS3Record to match against selections
[out]	ppselecttime	Pointer-to-pointer to return the matching MS3SelectTime entry

Returns: A pointer to matching MS3Selections entry successful match and NULL for no match or error.

◆ ms3_addselect()

int ms3_addselect	(	MS3Selections **	ppselections,
		const char *	sidpattern,
		nstime_t	starttime,
		nstime_t	endtime,
		uint8_t	pubversion )

extern

Add selection parameters to selection list.

The sidpattern may contain globbing characters.

The starttime and endtime may be set to NSTUNSET to denote "open" times.

The pubversion may be set to 0 to match any publication version.

Parameters

[in]	ppselections	MS3Selections to add new selection to
[in]	sidpattern	Source ID pattern, may contain globbing characters
[in]	starttime	Start time for selection, NSTUNSET for open
[in]	endtime	End time for selection, NSTUNSET for open
[in]	pubversion	Publication version for selection, 0 for any

Returns: 0 on success and -1 on error.

MessageOnError - this function logs a message on error

◆ ms3_addselect_comp()

int ms3_addselect_comp	(	MS3Selections **	ppselections,
		char *	network,
		char *	station,
		char *	location,
		char *	channel,
		nstime_t	starttime,
		nstime_t	endtime,
		uint8_t	pubversion )

extern

Add selection parameters to a selection list based on separate source name codes.

The network, station, location, and channel arguments may contain globbing parameters.

The starttime and endtime may be set to NSTUNSET to denote "open" times.

The pubversion may be set to 0 to match any publication version.

If any of the naming parameters are not supplied (pointer is NULL) a wildcard for all matches is substituted.

As a special case, if the location code (loc) is set to "--" to match an empty location code it will be translated to an empty string to match libmseed's notation.

Parameters

[in]	ppselections	MS3Selections to add new selection to
[in]	network	Network code, may contain globbing characters
[in]	station	Statoin code, may contain globbing characters
[in]	location	Location code, may contain globbing characters
[in]	channel	channel code, may contain globbing characters
[in]	starttime	Start time for selection, NSTUNSET for open
[in]	endtime	End time for selection, NSTUNSET for open
[in]	pubversion	Publication version for selection, 0 for any

Returns: 0 on success and -1 on error.

MessageOnError - this function logs a message on error

◆ ms3_readselectionsfile()

int ms3_readselectionsfile	(	MS3Selections **	ppselections,
		const char *	filename )

extern

Read data selections from a file.

Selections from a file are added to the specified selections list. On errors this routine will leave allocated memory unreachable (leaked), it is expected that this is a program failing condition.

As a special case if the filename is "-", selection lines will be read from stdin.

Each line of the file contains a single selection and may be one of these two line formats:

SourceID [Starttime [Endtime [Pubversion]]]

or

Network Station Location Channel [Pubversion [Starttime [Endtime]]]

The Starttime and Endtime values must be in a form recognized by ms_timestr2nstime() and include a full date (i.e. just a year is not allowed).

In the latter version, if the "Channel" field is a SEED 2.x channel (3-characters) it will automatically be converted into extended channel form (band_source_subsource).

In the latter version, the "Pubversion" field, which was "Quality" in earlier versions of the library, is assumed to be a publication version if it is an integer, otherwise it is ignored.

Returns: Count of selections added on success and -1 on error.

MessageOnError - this function logs a message on error

◆ ms3_freeselections()

void ms3_freeselections ( MS3Selections * selections )

extern

Free all memory associated with a MS3Selections.

All memory from one or more MS3Selections (in a linked list) are freed.

Parameters

[in] selections Start of MS3Selections to free

◆ ms3_printselections()

void ms3_printselections ( const MS3Selections * selections )

extern

Print the selections list using the ms_log() facility.

All selections are printed with simple formatting.

Parameters

[in] selections Start of MS3Selections to print

Data Structures

Functions

Detailed Description

Data Structure Documentation

◆ MS3SelectTime

◆ MS3Selections

Function Documentation

◆ ms3_matchselect()

◆ msr3_matchselect()

◆ ms3_addselect()

◆ ms3_addselect_comp()

◆ ms3_readselectionsfile()

◆ ms3_freeselections()

◆ ms3_printselections()