• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

dbexpressions - expressions in Datascope

DESCRIPTION

Datascope includes a scalar expression calculator which is used for a variety of functions, including evaluating sort and join keys, and computing subsets. It may also be called directly to evaluate an expression. This manual page describes the calculator and gives some examples. The program dbcalc(1) is handy for exploring the calculator and figuring out what's wrong with an expression.

Valid Types

The calculator recognizes integers (numbers without a decimal point), real numbers (numbers with a decimal point), and strings (arbitrary characters surrounded by single or double quotes). Type conversion is automatic in most useful cases.

Field Values

Expressions are always evaluated with a reference to a single record in a Datascope table. The names of fields in that table are recognized, and appear unadorned, like a variable name.

Operators

The calculator recognizes most of the common c operators, including "?", "+", "-", "*", "/", "%", the bitwise operators "<<", ">>", "|", and "&", and all of the logical operators "<", "<=", "==", "!=", ">=", ">", "&&" and "||".

The operator ":=" is the assignment operator, and can be used when the left side is a field name.

The operator "." is the string concatenation operator.

The operators "=~" and "!~" introduce regular expression comparisons, which must take one of two forms:


    expression =~ /regular expression/
    expression !~ /regular expression/

The caret is the exponentiation operator, and corresponds to the FORTRAN "**".

A time expression may be represented between underscores, e.g. _ 1999-103 12:05 _.

The bitwise exclusive or and the bitwise not are not implemented.

Functions

A variety of functions are implemented. Following standard programming practice, they are announced by the presence of a parenthesized, comma separated list following the function name.

NULL keyword

The special name NULL is recognized in certain cases: in expressions where the left side is a field name, and the operator is "==", "!=", and ":=". The function null("fieldname") can be used to obtain the null value for a field.

Regular Expressions

Regular expressions are built into the calculator. When the operator is either "=~" or "!~", the term on the right is a regular expression, which must be surrounded by slashes (the awk syntax). The patsub function also uses regular expressions, and provides a way of changing character strings, or extracting substrings.

Arithmetic Functions

abs(x) absolute value
min(x,y) minimum of x, y
max(x,y) maximum of x, y
ceil(x) next integer >= x
floor(x) next integer <= x
sign(x) 1 if x>0, -1 if x<0, 0 otherwise
int(x) floor(abs(x)) * sign (x)
sqrt(x) square root
log(x) natural logarithm
log10(x) base 10 logarithm
exp(x) e^x
cos(x) cos of x (x in degrees)
sin(x) sin of x (x in degrees)
tan(x) tan of x (x in degrees)
atan(y,x) arctangent of angle from x axis to point (x, y)
nan(x) 1 if x is an IEEE Not-A-Number

Seismic Travel Times

ptime(delta,depth) elapsed time for first p-arrival
pphasetime(delta,depth) elapsed time for first p-arrival
from event at delta, depth
stime(delta,depth) elapsed time for first s-arrival
sphasetime(delta,depth) elapsed time for first s-arrival
from event at delta, depth
phasetime(phase, delta, depth) elapsed time for specified phase
for event at delta, depth
phase_slowness(phase, delta, depth) slowness for specified phase
for event at delta, depth
pphase_slowness(delta,depth) slowness of first p-arrival in s/km
from event at delta, depth
sphase_slowness(delta,depth) slowness of first s-arrival in s/km
from event at delta, depth
parrival() time of first p-arrival
(requires join of site and origin tables)
sarrival() time of first s-arrival
(requires join of site and origin tables)
arrival(phase) arrival of specified phase
phase_arrival ( velocity ) time of phase arrival,
given velocity in degrees/second
(requires join of site and origin tables)

Flinn-Engdahl Seismic and Geographic Regions

grn(lat,lon) geographic region number corresponding to lat, lon
srn(lat,lon) seismic region number corresponding to lat, lon
grname(lat,lon) geographic region name corresponding to lat, lon
srname(lat,lon) seismic region name corresponding to lat, lon

Spherical Geometry

distance(lat1,lon1, lat2,lon2) distance in degrees
between two points
azimuth (lat1,lon1, lat2,lon2) azimuth from point 1 to point 2
latitude(lat,lon, distance, azimuth) latitude of the point a distance
away from (lat,lon)
in the direction azimuth.
longitude(lat,lon, distance, azimuth) longitude of the point a distance
away from point (lat,lon)
in the direction azimuth.
km2deg(km) nominal conversion from kilometers to degrees
deg2km(deg) nominal conversion from degrees to kilometers

Epoch Time Calculations and Conversions

now the current epoch time
epoch(j) convert jdate to time
yearday(e) convert epoch to yearday
date2e(year,month,day,seconds) convert to epoch time
strtime(e) convert epoch to string
strdate(e) convert epoch to date string
strtdelta(e) convert time difference to string
strydtime(e) convert epoch to date string with yearday
epoch2str(e,f) convert epoch to string using format f
epoch2str(e,f,z) convert epoch using format f, timezone z

Character Functions

External files

Aggregate Functions


count()
count_table()
sum( expr )
sum_table( expr )
min ( expr )
min_table ( expr )
max ( expr )
max_table ( expr )
record()

count() returns the number of records in a table or group. sum() returns the sum of the expression expr evaluated over each record in the table or group. min() and max() return the minimum and maximum of the values of expression evaluated over each record in the group.

If a table is grouped, the unqualified aggregate functions work on the individual group. That is, max(time) on a grouped record finds the maximum value of the field time in that group. On the other hand, max_table(time) finds the maximum value of time in the grouped table itself.

The absolute record number (of the view when the table is not a base table) can be obtained from the function record().

EXAMPLE


% dbcalc -e demo.wfdisc 0 < examples
# Simple fields from the table
sta
         "CHM"
chan
         "BHZ"
time
          5/17/1992  21:55:15.200
wfid
         15871
jdate
         1992138
nsamp
         2527
calib
         1.19535
dir
         "wf/knetc/1992/138/210426"
dfile
         "19921382155.15.CHM.BHZ"
commid
         -1

# Character string comparisons
sta < "AAK"
         false
sta <= "AAK"
         false
sta >= "AAK"
         true
sta > "AAK"
         true

"AAK" < sta
         true
"AAK" <= sta
         true
"AAK" >= sta
         false
"AAK" > sta
         false

sta == "AAK"
         false
sta != "AAK"
         true
sta == sta
         true
"AAK" == "AAK"
         true
"AAK" != "AAK"
         false

# Regular expressions
"AAK" =~ /.*K/
         true
"AAK" =~ /A.*/
         true
"AAK" =~ /B.*/
         false

# Expressions involving time
time
          5/17/1992  21:55:15.200
time - 10
          5/17/1992  21:55:05.200
time < "1/27/92 4:45"
         false
time < "4:54:32  1992 Jan 28 "
         false
time - 0.7 < "4:54:38  1992 Jan 28 "
         false
time > "1992"
         true
time < "1993"
         true
time -1
          5/17/1992  21:55:14.200
time - -1
          5/17/1992  21:55:16.200
time > jdate
         true
time > jdate + 1
         false
time + "10"
dbcalc: Invalid Expression!!
dbcalc: Expression could not be compiled: time + "10"

time * 1.5
dbcalc: Invalid Expression!!
dbcalc: Expression could not be compiled: time * 1.5

time / 1.5
dbcalc: Invalid Expression!!
dbcalc: Expression could not be compiled: time / 1.5

time + time
dbcalc: Invalid Expression!!
dbcalc: Expression could not be compiled: time + time

# Real Expressions
4.0 * 3.0
         12
4.0 - 3.0
         1
12.0 / 3.0
         4
2.0 + 2.0
         4

4.8 * 3
         14.4
4.0 - 3
         1
12.0 / 3
         4
2.0 + 2
         4

calib * 1.5
         1.79303
calib / 1.5
         0.796903

10^5.3
         199526

# Integer Expressions
2 + 2
         4
2 * 2
         4
2 / 2
         1
2 - 2
         0
2^2
         4

# Logical operators
0 && 0
         false
2 && 0
         false
2 && 2
         true

2 || 0
         true
2 || 2
         true
0 || 0
         false

0 ? 1 : 2
         2
1 ? 1 : 2
         1

0 ? 1.5 : 2.5
         2.5
1 ? 1.5 : 2.5
         1.5

0 ? "hi" : "bye"
         "bye"
1 ? "hi" : "bye"
         "hi"

# Assignments
calib
         1.19535
calib := 10.35
         10.35
calib
         10.35
calib := 1.2
         1.2

sta
         "CHM"
sta := "AAK"
         "AAK"
sta
         "AAK"
sta := "CHM"
         "CHM"


# Functions
distance ( 0.0, 0.0, 5.0, 5.0 )
         7.06657
azimuth ( 0.0, 0.0, 5.0, 5.0 )
         44.8908
latitude ( 0.0, 0.0, 5.0, 5.0 )
         4.98093
longitude ( 0.0, 0.0, 5.0, 5.0 )
         0.43688

abs ( -5.0 )
         5
sqrt (10.0 )
         3.16228
log ( 2 )
         0.693147
log10 ( 125 )
         2.09691
exp ( log ( 2 ) )
         2

epoch ( 1987244 )
          9/01/1987   0:00:00.000
epoch ( jdate )
          5/17/1992   0:00:00.000
yearday ( time )
         1992138
strdate ( time )
         " 5/17/1992"
strtime ( time )
         " 5/17/1992  21:55:15.200"
date2e ( 1987, 5, 12, 2*3600+34*60+5.35 )
          5/12/1987   2:34:05.350
now
dbcalc: Invalid Expression!!
dbcalc: eval : field 'now' not found in database.

now()
          8/17/1995  16:53:58.000

ptime ( 5, 0 )
         76.2738
stime ( 5, 0 )
         135.902

# Null fields
sta == NULL
         false
chan == NULL
         false
time == NULL
         false
jdate == NULL
         false
calib == NULL
         false
dfile == NULL
         false
commid == NULL
         true
clip == NULL
         true
segtype == NULL
         false
instype == NULL
         false

# String Concatenation and substitution

sta . '/' . chan
         "CHM/BHZ"
patsub ( chan, "Z", "N" )
         "BHN"
patsub ( sta . "/" . chan, '([a-z]+)/([a-z]+)', '$2/$1' )
         "CHM/BHZ"

BUGS AND CAVEATS

min and max always return a floating point value, and do not understand max and min as applied to a character string. phasetime and phase_slowness require a specific phase to exist in the travel time tables. If at a certain distance only Sb or Sg exists, and you request S, phasetime will return a -1.

AUTHOR

Daniel Quinlan
Printer icon