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

 

NAME

pktchannelcalib_new, pktchannelcalib_free, pktchannelcalib_get - get calib, response and site info

SYNOPSIS

#include "brttpkt.h"

PktChannelCalib *
pktchannelcalib_new (char *dbname,
	int need_calib, int need_response, int need_site)

int
pktchannelcalib_free (PktChannelCalib *ch)

int
pktchannelcalib_get (PktChannelCalib *ch,
	char *snet, char *ssta, char *schan, char *sloc, double time, int check,
	char *sta, char *chan, double *lat, double *lon, double *elev,
	double *calib, double *calper, char *segtype, Response **response)

DESCRIPTION

These routines provide a means for retrieving site and instrument response information from a database in an efficient manner to support ORB waveform packet processing. This utility is similar in function to dbget_calib(3) but it has a number of differences. The reason for these routines is to avoid the severe performance penalty that would result if the traditional datascope routines were used directly for each ORB waveform packet to form the time-varying views that would be necessary in order to retrieve the instrument and site information. Because packet rates can easily be in excess of hundreds of packets per second, trying to form datascope views at this rate would use up an inordinate amount of system resources. These routines instead cache the results of the database view operations into two associative arrays that are keyed on the SEED codes. The database view operations are only performed when 1) a new station or station-channel is seen in the data stream, 2) the time of the ORB packet is outside of the range of the time from a previous view generation, or 3) it appears that one or more of the datascope table files have been modified.

pktchannelcalib_new creates a new packet channel calib object and returns a pointer to the object. This pointer is used as a handle for subsequent operations. The need_calib flag should be set of the calib, calper and segtype parameters are desired in subsequent calls to pktchannelcalib_get. Note that the calib, calper and segtype values are obtained from the calibration table. The need_response flag should be set of the instrument response function is desired in subsequent calls to pktchannelcalib_get. A Response structure is returned in the *response pointer and this structure is obtained by reading and parsing the external response file referenced in the joined view of sensor->instrument. The need_site flag should be set if the site latitude, longitude and elevation are desired in subsequent calls to pktchannelcalib_get. These parameters are obtained from the site table.

pktchannelcalib_free frees all resources associated with a packet channel calib object.

pktchannelcalib_get is used to retrieve the parameters from either the cached values or from new database views. This switching is done automatically. The subject station-channel is specified through the SEED snet, ssta, schan and sloc codes. The sloc code can be set to a NULL string (not to a NULL pointer). Translation from SEED to css3.0 naming conventions for station-channel names is done automatically using the foreign(3) routines. The packet start time is specified by time which is used to form views and determine if cached views are no longer valid. The application programmer can control how often the database table files are checked for modification time with the check argument. If this argument is set, then the table modification times are determined, otherwise the table modification times are not determined (they are always determined when the database is first opened regardless of the check argument). This allows the application programmer to prevent excessive calls to the system stat(2) routine. The css3.0 station and channel codes are returned in sta and chan. The station latitude, longitude and elevation are returned in *lat, *lon and *elev (only if the need_site flag was set in pktchannelcalib_new). The instrument calib, calper and segtype are returned in *calib, *calib and segtype (only if the need_calib flag was set in pktchannelcalib_new). The instrument response function is returned in *response (only if the need_response flag was set in pktchannelcalib_new).

RETURN VALUES

pktchannelcalib_new returns a packet channel calib object handle (pointer to a PktChannelCalib structure) or NULL if there is an error. If there is an error, then messages are left on the error register.

pktchannelcalib_get returns an integer bitmap that indicates which of the output values were successfully returned or -1 if there is an error. If there is an error, then messages are left on the error register. The bitmap masks for each returned value are as follows.

LIBRARY

-lbrttpkt $(DBLIBS)

SEE ALSO

foreign(3), dbget_calib(3)

AUTHOR

Danny Harvey
Printer icon