Originated by DavidK 2001/07/17.



Last touched by DavidK 2001/07/17.





HOW TO use the Earthworm Database API (EWDB_API)?



This document contains a list of frequently asked questions,

about working with the EW Database and EWDB_API.



1) What's the difference between an Event and an Origin?



A: An Event is a catch all means of associating data.  In 95% of

the cases, an Event will represent an earthquake.  An Origin, 

along with derived magnitudes and mechanisms, represents an estimate

of what happened during a quake.  An Origin is specifically a

guess as to where the quake originated.  There may be multiple guesses

from multiple institutions, that all belong to the same quake.  

Following the analogy, their may be multiple Origins associated with

a single Event.  The Origins represent estimates or guesses as to

where the quake originated, and there may be more than one.  In most

cases, users will be interested in a single best guess, which the

DBMS terms the Preferred Origin.  One or more Magnitudes may be 

associated with each Origin.  Most users will also be interested in

a preferred magnitude, or atleast a preferred magnitude of each 

type(ML,MD,MW).  Multiple waveforms, picks, and amplitudes

may also be associated with the Event, even though they are not associated

with the Preferred Origin or Magnitude.



The remaining 5% of uses for Event are imagined to be very diverse, 

where the only thing the Events have in common is that they are used

as an associator to associate a bunch of data for a given purpose, 

such as associating a bunch of picks and waveforms for a tremor.



2) What is the EWDB_APPS_LIB and what is it used for?

The EWDB_APPS_LIB is a collection of C functions that allow convenient

access to data in the database.

The calls within the EWDB_APPS_LIB that are oriented towards the

95% usage(described in #1).  They insert and retrieve information 

from the database oriented around Events with a single preferred 

origin, with a bunch of derived magnitudes.  For each channel 

associated with the Event there may be arrivals, amplitudes, and 

waveforms, which may be associated with the origin and/or magnitudes.  

The EWDB_APPS_LIB functions, call EWDB_API_LIB functions, so that 

everything goes through "the API", but the EWDB_APPS_LIB functions 

provide a fairly simple interface to the application developer on 

one end, and then break down all of the neccessary work into small 

blocks that can be handled by individual EWDB_API_LIB functions 

on the other side.





2) How do I insert an Event into the database?



Because the potential uses for Event are envisioned to be so vast,

there are many lower level calls.  Each call has a certain purpose,

such as creating an event, inserting an origin, inserting an arrival,

associating an arrival with an Event, etc...

In an attempt to effectively serve the 95% of clients that are 

interested in stuffing earthquakes, there is a call 

ewdb_apps_PutDBEventInfo(), that reads a mammoth structure (and all

of its substructures) and inserts its contents into the DB.  So you

must fill the structure(s) and then make a single call to stuff it

into the DB.  If the structures and the function does not serve your

needs, then you can always do all the legwork yourself by calling the

lower level EWDB_API_LIB functions.





3) How do I retrieve an Event from the database?



Similar to ewdb_apps_PutDBEventInfo() mentioned above, there is 

an EWDB_APPS_LIB function ewdb_apps_GetDBEventInfo(), that provides

a means of retrieving the data normally associated with an Event into

a single mammoth structure.





4) What is a channel?



Um.....  This is a simple question, but talk of channels usually leads

to channel naming which is a very ugly topic.

A channel is an imaginary pipe.  At one end is the ground, and at

the other end is a seismic processing system.  Ground motion

goes into the channel and a set of digital waveforms comes out.

Starting at the ground end, the channel usually begins with 

a seismic sensor that converts ground motion to analog data,

then through a digitizer with zero or more amplifiers, decimators,

and other junk, and pops out the far end of the pipe as digital 

waveforms.  The channel is the pipe, or the path that the data

took to go from ground motion to digital waveforms. 



Station or Site:  A relatively small physical site where zero or

more pieces of seismic monitoring equipment may be placed.



Component:  A piece of seismic monitoring equipment at a Site that

measures one range of seismic motion.



Channel:  A path/pipe from a Component to a seismic acquisition/processing

system that utilizes digital waveforms.



Network:  A seismic data acquisition and processing system/organization 

that is made up of a lot of paperwork, people, and seismic monitoring 

equipment.  The University of Utah has a seismic network.



A confusing twist:

Channels don't have to have anything to do with seismic

data.  They could be used to transmit tide levels, geomagnetic information,

State of Health, or GPS info.  For the most part, we will stick

to talking about the 95% case where we are transmitting seismic data.





5) How do I lookup a channel in the EWDB?

In order to lookup a channel in the DB, you first need 

someway of identifying the channel.  The EWDB utilizes

identification numbers (IDs) to identify each entity in 

the world of seismic processing.  The ID for a channel is

called an "idChan".  You lookup a channel in the DB via its

idChan.  This kind of begs the question: 

How do I get the idChan for a channel?



6) How do I get the idChan for a channel?

Ah, the heart of the matter....

The best way to get an idChan for a channel is to find

a good psychic. 

(http://google.yahoo.com/bin/query?p=psychic+channel+id&hc=0&hs=15)



If that fails, then the next step is to try to find a channel utilizing

some sort of naming scheme.  There are two routes to go: the internal,

or the external(cheater).



The Internal

Given the SCNL(Site, Channel, Network, Location) codes for a particular

component, and a time of interest, you can call ewdb_api_GetidChansFromSCNLT(),

to get a list of channels that come from a given component.  The SCNL identifies

a Component (see #4), and then the time allows the database to lookup what 

channels were generated from that component at the given time.  If you are pulling

SCN from an automated Earthworm system, be sure to read the "External" section.



The External

Earthworm and potentially other seismic processing software is based

upon an imperfect channel naming system.  Earthworm channel naming

is currently based upon SCN (Station, Channel, Network).  For most 

channels, this SCN identifies the component in the field from which

the data came.  In some instances, where there are arrays, or multiple

instruments with the same component at the same site, then the SCN

is bastardized in order to be unique.  Usually the station name is

fudged to include a component reference.  Any which way, the naming

system at best identifies the instrument in the field that recorded

the data, and not then entire path that the data traveled before

hitting the network processing center.  So, in order to get an

idChan, you need to use a cheater table.  The basis of the cheater

table, is that the network operator has apriori knowledge about

what SCN labeled data is associated with which channel.  The operator

creates a channel(10 for example) in the database, and then sets up the 

cheater table, so that data coming in that is marked with SCN XXX,EHZ,US, 

gets associated with channel #10.  A person looking for idchan for

data that is marked as XXX,EHZ,US, can utilize the same table.

Use int ewdb_apps_RetrieveIdChanExternal(), to lookup an idChan via

the default earthworm cheater table.



Example:

Data is acquired and digitized at a site in the field.  The data is given

the SCN AAA,EHZ,XX, and then piped out to two institutions, who apply two

different sets of filters to the data, resulting in two differnt data streams,

both labeled AAA,LHZ,XX.  How do you know which one is which?  You don't

by looking at the labels inside the data streams, but the operator knows 

he/she/it is getting data from institution A, not institution B.  So he

adds a link in the cheater table between AAA,LHZ,XX, and a channel, and

he hopes that data from same component via institution B, never finds its

way into his real time network.





6) Why should I use the EWDB_API_LIB or EWDB_APPS_LIB functions?

The EWDB_APPS_LIB functions provide convenient ways of accomplishing

popular tasks.  By using the EWDB_APPS_LIB functions, you save yourself

time by not having to go through all of the legwork to break out 

data into small chunks that can be used with EWDB_API_LIB, you use

the same code as many other applications, which means it is fairly well

tested, and it probably works right, even if it doesn't match the 

underlying code changes or doesn't match specifications.



The EWDB_API_LIB is the only supported method for writing data to the EWDB.

(Note the EWDB_APPS_LIB utilizes the EWDB_API_LIB, so it is therefore

 supported).

Starting with EW version 6.0, the EWDB_API_LIB will be backwards compatible,

(reasonably so), but the underlying SQL code and table layout probably will

not be.  The EWDB_API_LIB severely limits the way that data can be written

to the database, and applies business logic rules to data being entered.

Without it, assumptions by applications on the retrieval end may fail.

There are a lot of things that can go wrong when business logic rules and

underlying assumptions are circumvented, and it makes it very difficult

to troubleshoot and maintain a production grade database under such situations.

The idea is that there is a limited number of paths for data to go through

on the way in, and so there is a limited number of things that can go wrong, 

and a limited number of paths that must be tested when things go awry.

The more paths that are added, the more potential for trouble, and the more 

time required to troubleshoot problems.  As much business logic as possible

has been integrated into the PL/SQL procedures that lie inside of the API,

but some of the neccessary logic was built into the API, and thus circumventing

the API, potentialy circumvents logic.  TECHNICALLY, IT WILL BE MUCH MORE 

DIFFICULT TO SUPPORT DATABASES THAT ALLOW APPLICATIONS ACCESS VIA METHODS 

OTHER THAN THE EWDB_API_LIB!





7) How do I get ahold of the developers of the EW v6 EWDB_API_LIB, to thank

them for doing such a wonderful job, or heaven forbid, choking the snot out

of them because functions don't work??



While it is rumored that EWDB_API developers frequent bazaars, this is

probably only at night and in the darkest of corners.  While never going

near catherdrals, these developers live in Ivory Towers, and never on the

ground floor(the 5th floor is popular).  When not writing code, and fixing

bugs, they practice writing in Greek and speaking in tongues.



Due to the excessive number of requests and death threats, direct contact

with the developers is limited, and you should contact the powers that be

with all requests, complaints, and questions.  A good place to start is

the person who distributed this product to you.  As a last resort, you

can always post items to the Earthworm Mailing List ( earthw-list@nmt.edu )









