NAME

perldb - perl interface to Datascope and related functions

DESCRIPTION

The Datascope extension to perl(1) provides most of the functionality of c. Most of the extension routines generate a perl error when an error occurs, rather than returning a bad-result code. These errors can be intercepted by using the perl function eval. When an error occurs, the returned message is the complete contents of the error log.

Database pointers are most conveniently kept in perl arrays, though because of the perl calling conventions, you may alternatively keep them in a set of scalar variables.

The various predefined constants are part of the package, but dbquery also accepts a string. Note that dblookup recognizes dbNULL and dbSCRATCH in the record field.

These extensions must first be loaded with a use statement:


use Datascope ;

For examples of perl scripts using the Datascope extension, please review the scripts in $ANTELOPE/example/perl.

Following are brief descriptions of the functions implemented.

Opening/Closing a Database/Table

Manipulating Fields and Records

Here's an example of how to catch an error when using dbaddv:


eval { $db[3] = dbaddv ( @db,
            "name", $name,
            "execution", $execution ) ;
} ;
if ( $@ ne "" ) {
    print STDERR "$@" ;
}

Note, however, that $db[3] is not filled in when dbaddv fails. However, an error message is left in $@ which specifies the conflicting row.

An alternative approach might be to use dbgetv to ask for the database pointer corresponding to one of the base tables in the view, e.g. '$dbs = dbgetv(@dbview, "origin" )'. The returned string dbs can be converted to a database pointer with split: "@db = split(' ', $dbs);".

Forming Views

Miscellaneous Datascope Functions

Waveforms

Elog Error Handling Routines

Parameter Files

Special Functions

Time Conversion Routines

State Files

Foreign Keys

These routines use the snetsta, anetsta, schanloc and achanaux tables and the foreign(3) key routines to map between CSS3.0 station/channel naming conventions and the different conventions of autodrm and SEED.

Simple Ring Buffers

These simple ring buffers hold only an ordered list of time/value double floating point pairs, as described in ring(3).

A ring buffer is opened (or created if it doesn't already exist) by openring or created by newring, which take the arguments below. An existing ring buffer is overwritten (the old values are lost) by a call to newring.

An open ring buffer is closed with closering.


newring ($filename, $id, $depth, $flags ) ;
$rb = openring($filename, $id, $depth, $flags ) ;

closering($rb) ;

time/value pairs are added to a ring buffer with pushring. This routine reorders the list (if necessary) to keep it in time order.

cramring adds time/value pairs to the ring, but according to some algorithm (the fourth parameter). The collapse algorithm only inserts a new value when it's different from the previous value (except that the second pair entered is always inserted into the ring). Pairs are NOT reordered; a pair with a time previous to the latest entry in the ring is silently discarded.

countring returns the number of time/value pairs currently in the ring buffer. tallyring returns the number of time/value pairs within tdelta seconds before the latest pair currently in the ring buffer.

getring returns the i'th time/value pair from the ring buffer, where i=0 gets the most recent time, and countring(rb)-1 returns the oldest time.


pushring($rb, $time, $value) ;
cramring($rb, $time, $value, "collapse") ;

($latest_time, $latest_value) = getring($rb, 0) ;
($oldest_time, $oldest_value) = getring($rb, countring($rb)-1) ;

minring, maxring, avgring and changedring take two arguments -- the ring buffer and number of seconds before latest ring buffer entry -- and return the minimum, maximum, and average value for the time period from time(i=0) to time(i=0)-tdelta; minring and maxring also return the index corresponding to the minimum and maximum value. changedring returns one if consecutive values in the ring buffer have changed over the past tdelta seconds.

findring searches the ring buffer over the specified time period for a specific value.


($minvalue, $jmin) = minring($rb, $tdelta) ;
($maxvalue, $jmax) = maxring($rb, $tdelta) ;
$avgvalue = avgring($rb, $tdelta) ;

if ( &changedring($rb, 10.0) ) {
    &send_warning() ;
}

$index = &findring($rb, $value, $tdelta) ;
if ( $index < 0 ) {
    print STDERR "*not found*\n" ;
} else {
    print STDERR "$value found at index $index\n" ;
}

meanring calculates the mean and standard deviation for time/value pairs within tdelta of the latest entry. linearfitring returns the linear least square best fit line which matches the pairs within tdelta of the latest entry.


($npts, $mean, $stddev) = meanring($rb, $tdelta) ;
($npts, $slope, $y0, $correlation) = linearfitring($rb, $tdelta) ;

Coordinate Transformations

RETURN VALUES

dbopen, dbopen_table, dbopen_database, dblookup, dbjoin, dbtheta, dbsubset, dbsort, and dbgroup all return database pointers.

dbget returns a single field, record, or table.

dbgetv returns a list of all the field values requested; when a dbptr is the requested field, it is returned as a single string which must be split into the various components, e.g.:


@db = split ( ' ', $dbptr ) ;

dbput, dbputv, dbsave_view, dbunjoin, dbcompile, dbadd_remark, dbmark, dbclose, dbdelete, dbfree, dbtruncate, dbcrunch, dbdestroy, and limit have no return value.

dbadd, dbaddchk, dbaddnull and dbaddv return the record number of the add record.

dbex_eval returns the value of the expression.

dbfind returns a record number, or -1 if no matching record was found.

dbextfile returns the name of the external file.

dbget_remark returns the requested comment from the remark table.

dbquery returns the requested value. Usually this is a scalar, but in the case of dbSCHEMA_FIELDS, dbFIELD_TABLES, dbVIEW_TABLES, dbSCHEMA_TABLES, dbTABLE_FIELDS, dbPRIMARY_KEY, dbALTERNATE_KEY, and dbFOREIGN_KEYS, a list is returned.
dbquery of dbFIELD_TYPE returns the string dbINTEGER, dbREAL, dbTIME, dbDATE, dbYEARDAY, dbSTRING, or dbDBPTR.
dbquery of dbLINK_FIELDS returns an array.

dbnojoin and dbmatches return a list of record numbers.

dbnextid returns the integer next id.

elog_mark returns an integer

epoch and str2epoch return a real time.

yearday returns an integer = year * 1000 + day of year.

epoch2str, strtime, strdate, strydtime and strtdelta return a formatted string representing a time.

datapath and datafile return file names, or undef if no matching file is found.

grn and srn return integers; grname and srname return strings.

askyn returns either 0 (no) or 1 (yes). askynaq returns 2 (all) or 3 (quit) in addition to 0 and 1. ask returns the reply string.

pfget returns either a string, or a reference to a list or a reference to an array.

SEE ALSO

dbconstants(5)
dbintro(3)
dbschema(5)

BUGS AND CAVEATS

When an error occurs during the execution of one of these calls, the routine does not return normally, usually causing the script to abort. You must wrap a call inside an eval statement if you wish to continue a script under these conditions.

When referring to the (more detailed) c documentation for these routines, be sure to look at the man pages in section 3, rather than the man pages in section 1. dbdelete(3) (as implemented here) deletes one record at a time, whereas dbdelete(1) takes as input a view and deletes every record in the view.

Needs better method of getting the Datascope #defined codes. (dbREAL, dbNULL, dbRECORD_COUNT, etcetera).

AUTHOR

Daniel Quinlan

Table of Contents
Antelope Release 5.0-64 SunOS 5.10 2010-11-11
Boulder Real Time Technologies, Inc For more information, contact support@brtt.com