NAME
antelope - Introduction to the Antelope Programming Interfaces
DESCRIPTION
The Antelope software provides a wide variety of tools for
managing and working with seismic data. In addition, it provides
documented interfaces for developing new tools in c, tcl/tk, shell
script, fortran or perl. There are contributed interfaces to matlab
and php.
This man page provides a brief overview of the
programming resources.
The primary implementation language for Antelope
is ANSI c; we are moving toward using the 1999 extensions.
Most of the Antelope programs are built upon a relational database,
using a variation of the CSS 3.0 schema. The underlying RDBMS
is Datascope, and is part of the system.
Datascope represents tables as fixed-format, plain ascii text files;
waveform data is kept in external binary files which may have a variety
of formats. A tutorial introduction to Datascope
is found in the doc directory of the distribution.
FILESYSTEM ORGANIZATION
Antelope resides in a single
directory,
/opt/antelope, which is organized in a manner reminiscent of standard UNIX
practice for /usr. Please refer to the man page
hier(5) for a more
detailed description.
ENVIRONMENT
Antelope relies on a single environment variable,
ANTELOPE, to locate the root of its filesystem hierarchy. Refer to
antelopeenv(5) for a description of this and other optional
environment variables.
MAKEFILES
The Makefiles which generate Antelope are relatively simple, and
follow a standard format. Refer to
antelopemakefile(5) for a detailed
description. See
antelopemake(5) for more discussion of the rules file --
included in every Makefile -- which makes the simplicity possible.
LIBRARIES
This is intended only to introduce the various libraries, not to
provide a comprehensive description. The documented libraries have
extensive man pages. However, some libraries are undocumented, and
likely to remain so. The only documentation for these libraries is
the code itself.
deviants
Antelope's approach to portability is to concentrate the architecture
differences across the supported architectures into routines with equivalent
call structure in the deviants library. Although the implementation varies
from one platform to another, the routines should be compatible.
stock
The stock library has a variety of generally useful routines;
The include file "stock.h" includes declarations for most
routines and interfaces in this library, and a few common macros, notably
for using malloc.
Some of the more important interfaces are:
-
list manipulation: tbl(3)
Variably sized dynamic lists are extremely useful, and the tbl library
provides a standard interface.
-
associative arrays: arr(3)
Similarly, associative arrays (arrays where the index is a character string,
rather than an integer) are often useful.
-
sorted tables: stbl(3)
While associative arrays are indexed by a character string, these "sorted"
tables are indexed by an arbitrary structure, for which the user must supply
a comparison function. Note that the comparison function must strictly
order the structures; that is, there must be a unique "correct" sorted order
for the set of structures that will be kept in the sorted table.
-
error reporting: elog(3)
A central error reporting scheme is essential for developing libraries
which work together; these routines standardize the reporting of errors.
-
sorting: isort(3), quicksort(3), shellsort(3)
These are a few alternatives to the standard UNIX quicksort qsort.
-
string manipulation: strings(3)
A variety of addition string routines, including pattern substitution
and accumulation of very long strings.
-
parameter files: pf(3)
Programs often need more parameters than comfortably
fit on the command line. These
routines provide a standard interface to a parameter file with a
general and readable format.
-
time conversions: epoch(3)
The routines convert from ascii representations of time to binary
epoch times (doubles), and vice versa.
-
units: units(3)
Convert between different sets of units (e.g., km/sec to miles/hour).
-
bit vectors: bitvectors(3)
manipulate arrays of bit flags
-
path manipulation: path(3)
Clean up paths, find paths from one directory to another, convert
paths to absolute or relative paths.
-
byte swapping: byteswap(3)
Convert representations between the local host and another
architecture for standard data types like int, double, and float.
ds
This library implements the Datascope RDBMS; start with
dbintro(3).
orb
This library implements the protocol for communication with the
orbserver(1), and is used by all programs which read from or write
to the orb ring buffer. See
orb(3) for more detail.
Pkt
This library implements the decoding and the creation of a variety
of orb packets.
See
unstuffPkt(3) and
stuffPkt(3).
coords
The coords library has a few routines for coordinate manipulation and
conversion.
trvltm
This is a general interface to arbitrary travel time routines, which
must be provided in a dynamic library and comply with a specific interface.
tttaup
These routines provide a c interface to the library written by
Ray Buland and Brian Kennett (BSSA, v. 73, pp. 1271-1302).
See
ptime(3). They provide a trvltm compliant interface.
tks
This library implements the tk send routine independent of tk, allowing
it to be easily embedded in other programs without embedding tcl/tk.
tksend(1) is an example of an application which uses this library.
GRAPHICS
Several graphics libraries are provided.
gpl
These routines implement the trace display used by dbpick and other programs.
grx
These routines implement niceplot, a set of routines for generating a
variety of two dimensional plots.
DATAFORMAT CONVERSION
ah
read and write ah-format files
sac
read and write sac-format files
dbl2
This library implements an early set of database access routines on top
of Datascope.
They should not be used for any new development.
scv2
Implements the SCV Station Channel View of a CSS database. This is
useful for organized access to the actual waveform data, and is used
by dbpick and a number of other routines. These should not be used for new
development.
mw
These routines implement multi-taper spectral analysis.
tr
This library implements some waveform manipulation routines
based on Datascope. See
trintro(3).
brttfilter
brttpool
This contains global variables which might be used in multiple perl extensions,
e.g. orb and Datascope. Putting them in a third library allowed these global
variables to be shared rather than separately instantiated.
response
These routines read and write ascii response files in a format originally
specified by CSS -- see
response(3).
EXTENSION LIBRARIES
tclds
This library provides a tcl interface to the Datascope routines;
refer to
Datascope(3t) for some documentation of the added tcl commands.
The library routines for perl and tcl are actually contained in
$ANTELOPE/data/perl and $ANTELOPE/data/tcl.
tkgpl
This is a tk interface to the gpl routines, used by tkdbpick.
tkpixmap
pixmaps for tcl/tk
cgeom
Computational Geometry Library
forb
routines for reading and writing orb packets in a flexible format to disk.
tclorb
tkttgrid
wffil
wffilbrtt
SCRIPT EXTENSION LIBRARIES
perl
These are perl subroutines which may be of general interest.
The directory also contains perl packages which interface to the Datascope
library and many related Antelope c interfaces ("use Datascope"), a package for orb
connections ("use orb"), and a package for system configuration related interfaces ("use sysinfo").
data/tcl
These are tcl/tk subroutines which add to the basic tcl/tk routines.
They include
UNDOCUMENTED LIBRARIES
The following libraries are used by some programs, but are not
documented, and are unlikely ever to be documented. Many have
some descriptions embedded in the source code.
ev
Implements an event view of a CSS database, similar to the SCV station channel
view.
io
Access to fortran direct access files.
map
Access to the Antelope map database -- this is used by dbmapevents.
math
Various special functions, including Bessel functions and Fourier transforms.
ol
Implements some xview-like widgets; used by dbpick and dblook.
ENVIRONMENT
Refer to
antelopeenv(5).
BUGS AND CAVEATS
Please report bugs to
support@brtt.com.
Please bear in mind that a complete description
of the problem, including an example of how to generate it, what you
expected and what you actually saw, and any
error messages generated is essential to diagnose and fix
problems. See bugs(5) and reporting(5) for further suggestions on how to report
problems.
Do not send problem reports to individual email addresses at
BRTT; they will not be answered. To receive a response, only
use support@brtt.com. Requests sent to support@brtt.com
are read by multiple people and will be responded to in a timely manner.