• Antelope Release 5.9 Mac OS X 10.13.2 2019-05-01

 

NAME

pktchannel2trace_new, pktchannel2trace_free, pktchannel2trace_destroy, pktchannel2trace_put_from_db, pktchannel2trace_put - trace data accumulator

SYNOPSIS

#include "brttpkt.h"

PktChannel2Trace *pktchannel2trace_new (Dbptr dbmaster,
                Dbptr dbtrace, Dbptr dbwf, int need_calib,
                int need_response, int need_site)

int pktchannel2trace_free (PktChannel2Trace *pt)

int pktchannel2trace_destroy (PktChannel2Trace *pt)

int pktchannel2trace_put_from_db (PktChannel2Trace *pt,
                char *sta, char *chan_expr, int calibfrommaster,
		double tstart, double tend)

int pktchannel2trace_put (PktChannel2Trace *pt,
                PktChannel *pchan, int calibfrommaster,
		double tstart, double tend)

int pktchannel2trace_get_stats (PktChannel2Trace *pt,
                char *sta, char *chan, int *ngood, int *nbad)

DESCRIPTION

These routines provide a utility for accumulating waveform data for known and finite time windows either in real-time from an ORB, or from a database, or a combination of both real-time and database sources. Regardless of the input source, waveform data is accumulated into an output trace database that uses the Trace4.0 schema (try dbhelp Trace4.0 to see the schema definition).

The accumulation of time segments from potentially time fragmented data sources, such as certain real-time packet data, is done in a manner similar to cdorb2db(1). Upon reception of the first input data source, whether from a database or from an ORB packet, the start time of the first sample and the sample rate are used to define a constant time sampling grid over the requested time interval. The sample values in the entire grid are then pre-filled with official "gap" floating point sample values, using trfill_gap(3). As data is accumulated, each new sample value is projected into its proper slot within the fixed sample grid to replace the gap value, or any other existing value such as would happen with time overlapping data. After all data has been accumulated, the final data arrays in the output trace database will show gap sample values at sample times where there were no input sample values. It is the responsibility of the user to deal with the gaps in subsequent processing. A floating data sample value for determining the flagged gaps can be obtained by the call:



float gap_value;

trfill_gap (&gap_value, 1);

Note that even though this processing is very stable in the sense that it will always do something reasonable with new data that it is accumulating into the output sample grid, this processing will not work very well for data with extremely slippery timing or data where different segments are not approximately time registered. These routines make no attempt to measure or warn about timing irregularities.

pktchannel2trace_new creates a new pktchannel2trace object and returns a pointer to the object instance. This pointer is used as a handle for subsequent operations. dbmaster specifies a database pointer to a "master" database that contains instrument response and site characteristics. dbtrace specifies a database pointer to an output trace database (see the Trace4.0 schema using dbhelp(1)) and can be created with a call to trnew(3), or it can add into a previously accumulated trace database. dbwf is a database pointer to an optional waveform database that can be used as a source of the data. If dbwf.database is set to dbINVALID, then there is not input waveform database and all data will come from ORB packets. If calib, calper and segtype metadata is needed in the output trace database, then need_calib should be set to 1. If a complete instrument response function is needed in the output trace database, then need_response should be set to 1. If the station lat, lon and elev metadata is needed in the output trace database, then need_site should be set to 1.

A pktchannel2trace object is freed with pktchannel2trace_free.

pktchannel2trace_destroy is like pktchannel2trace_free with the addition of also destroying the associated trace database including freeing any allocated trace buffers.

pktchannel2trace_put_from_db will put waveform data for a single station, specified by sta, for the channels that match the chan_expr channel expression and over the time window from tstart to tend from the waveform database specified in the dbwf database pointer into the output trace database according to the rules described previously. If the calibfrommaster flag is set to 1, then the calib, calper and segtype metadata will be taken from the master database calibration table instead of directly from the waveform wfdisc table.

pktchannel2trace_put will put waveform data from a single ORB data packet channel, specified by pchan, and over the time window from tstart to tend into the output trace database according to the rules described previously. If the calibfrommaster flag is set to 1, then the calib, calper and segtype metadata will be taken from the master database calibration table instead of directly from the pchan structure. ORB packet channels are typically obtained from unstuffPkt(3). Note that all of the metadata processing and the station and channel codes in the output trace database will conform to the CSS station and channel naming conventions. This requires the SEED codes in pchan to be translated, which is done automatically using the foreign(3) keys routines along with the master database.

pktchannel2trace_get_stats will return the record number in the output trace database that corresponds to CSS station code sta and CSS channel code chan along with the total number of good data samples in ngood and bad or gapped data samples in nbad. If no row in the output trace database corresponds to sta and chan, then dbINVALD is returned.

Note that tstart and tend are only used the very first time a new station-channel is accumulated into the output trace database. If a particular station-channel already exists in the output trace database, then the start and end times are taken from the values in the trace database row and the tstart, tend values in the call arguments are ignored.

RETURN VALUES

pktchannel2trace_new returns a pktchannel2trace process handle (pointer to a PktChannel2Trace structure) or NULL if there is an error. If there is an error, then messages are left on the error register.

Everything else returns 0 if OK or -1 if there is an error. If there is an error, then messages are left on the error register.

LIBRARY

-lbrttpkt $(ORBLIBS)

SEE ALSO

cdorb2db(1)
trnew(3)

AUTHOR

Danny Harvey
Printer icon