Functions of the EW5 Oracle API

ArcFile2DB

Prototype:

int ArcFile2DB(

char * ArcFileName, char * author, char * szEventID);

Description:

Reads the hypoinverse arc file, converts it into DB event format and inserts it into he database.

Return Type:

int

Return Value	Description
EW_SUCCESS	Successful operation
EW_FAILURE	Failure -- see logfile for details.

Parameter	Type	Description
ArcFileName	char *	Name of Hypoinverse arc file to insert.
author	char *	Author to be assigned to the event.
szEventID	char *	External author ID.

RetrieveIdChanExternal

Prototype:

int RetrieveIdChanExternal(

EWDB_External_StationStruct * pStation);

Description:

Function creates or updates a component and associated channel in the DB using an external station table and a a cheater table to go from external station to chan. Upon successful completion it writes the DB ID of the new/update channel to pStation->idChan. This function ignores the pStation->idComp parameter.

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
pStation	EWDB_External_StationStruct *	Pointer to an EWDB_External_StationStruct filled by the caller.

InsertBodyAmp

Prototype:

int InsertBodyAmp(

EWDB_PhaseAmpStruct * pBodyAmp);

Description:

Function creates a body amplitude based station magnitude from the caller supplied information in pDurCoda. The function assumes that the caller has supplied all station magnitude information including summary magnitude data in the EWDB_PhaseAmpStruct. The caller need not fill in AmpBody related information as it is inappropriate. The pBodyAmp->idMagnitude and pDurCoda->idPick values must be valid existing Magnitude and Pick DB IDs respectively. The pDurCoda->idChan value must also be filled in with the DB ID of a valid existing channel.

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
pBodyAmp	EWDB_PhaseAmpStruct *	Pointer to a EWDB_PhaseAmpStruct filled by the caller.

InsertDurCoda

Prototype:

int InsertDurCoda(

EWDB_PhaseAmpStruct * pDurCoda);

Description:

Function creates a coda duration based station magnitude from the caller supplied information in pDurCoda. The function assumes that the caller has supplied all station magnitude information including summary magnitude data in the EWDB_PhaseAmpStruct. The caller need not fill in AmpBody related information as it is inappropriate. The pDurCoda->idMagnitude and pDurCoda->idPick values must be valid existing Magnitude and Pick DB IDs respectively. The pDurCoda->idChan value must also be filled in with the DB ID of a valid existing channel. Upon successful completion, the function writes the DB IDs of the newly created coda duration, coda termination, and station magnitude to pDurCoda->idDurCoda, pDurCoda->idTCoda, and pDurCoda->idMagLink respectively.

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
pDurCoda	EWDB_PhaseAmpStruct *	Pointer to a EWDB_PhaseAmpStruct filled by the caller.

DB2ArcFile

Prototype:

int DB2ArcFile(

EWDBid idEvent, char * ArcFileName);

Description:

Writes all information about the event in Hypoinverse archive format to the file.

Return Type:

int

Return Value	Description
EW_SUCCESS	Successful operation
EW_FAILURE	Failure -- see logfile for details.

Parameter	Type	Description
idEvent	EWDBid	Database ID of the event to retrieve.
ArcFileName	char *	Name of Hypoinverse arc file to write.

GetDBEventInfo

Prototype:

int GetDBEventInfo(

t1 p1, t2 p2, t3 p3);

Description:

desc

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success

Parameter	Type	Description
p1	t1	d1
p2	t2	d2
p3	t3	d3

GetDBEventInfo_Super> GetDBEventInfo_Super

Prototype:

int GetDBEventInfo_Super(

t1 p1, t2 p2, t3 p3);

Description:

desc

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success

Parameter	Type	Description
p1	t1	d1
p2	t2	d2
p3	t3	d3

GetTransformFunctionForChan

Prototype:

int GetTransformFunctionForChan(

EWDBid idChan, time_t tTime, EWDB_ChanTCTFStruct * pChanCTF);

Description:

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
idChan	EWDBid	The DB ID of the channel for which the caller wants to retrieve a cooked transform function.
tTime	time_t	Point in time for which the caller wants a cooked transform function for the channel. A time is required because the transform function varies over time as device properties are changed or the channel is altered.
pChanCTF	EWDB_ChanTCTFStruct *	Pointer to a caller allocated EWDB_ChanTCTFStruct where the function will write the cooked transform function and associated channel specific response information requested by the caller. DESCRIPTION Function retrieves the poles/zeroes based transform function, gain and sample rate for a given channel and time. The transform Function is used to transform recorded waveforms back into ground motion.

ConvertString2PZNum

Prototype:

int ConvertString2PZNum(

EWDB_PZNum * PZNums, int * pCount, int MaxPZNums, char * szNumString);

Description:

Function parses szNumString for a list of complex numbers. The function converts the list to an array of EWDB_PZNums, writes the list to PZNums, and writes the number of complex numbers converted to pCount.

Note:

This function should not be part of the exposed API. It is a utility function for converting Poles/Zeroes from a format useful in C(EWDB_PZNum) to a format useable in Oracle PL/SQL(string). It should never be needed by API clients, because they pass an receive Pole/Zero data as C structures and not strings.

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
PZNums	EWDB_PZNum *	Caller allocated array of pole or zero complex numbers.
pCount	int *	A pointer to an int where the function will write the number of EWDB_PZNums placed in PZNums.
MaxPZNums	int	The szie of the caller's buffer(PZNums) in terms of EWDB_PZNum structs.
szNumString	char *	Caller supllied string containing a list of complex numbers.

PutDBEventInfo

Prototype:

int PutDBEventInfo(

t1 p1, t2 p2, t3 p3);

Description:

desc

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success

Parameter	Type	Description
p1	t1	d1
p2	t2	d2
p3	t3	d3

CreateWaveform

Prototype:

int CreateWaveform(

t1 p1, t2 p2, t3 p3);

Description:

desc

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success

Parameter	Type	Description
p1	t1	d1
p2	t2	d2
p3	t3	d3

GetWaveformListByEvent

Prototype:

int GetWaveformListByEvent(

EWDBid idEvent, EWDB_WaveformStruct * pWaveformBuffer, EWDB_StationStruct * pStationBuffer, int BufferRecLen, int bIncludeStationInfo, int * pWaveformDescsFound, int * pWaveformDescsRetrieved);

Description:

Function retrieves a list of waveform descriptors and optionally EWDB_StationStructs for waveform snippets associated with the Event identified by idEvent.

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
idEvent	EWDBid	The DB identifier of the Event for which the caller wants a list of waveform snippets.
pWaveformBuffer	EWDB_WaveformStruct *	Pointer to a buffer allocated by the caller, where the function will write the list of waveform descriptors.
pStationBuffer	EWDB_StationStruct *	Pointer to a buffer allocated by the caller, where the function will write the component info for each waveform descriptor's channel. There is a 1-to-1 correlation between waveform descriptors and station/component descriptors, and they are in the same order. This parameter is ignored if bIncludeStationInfo is FALSE.
BufferRecLen	int	Length of the caller supplied buffers(pWaveformBuffer and pStationBuffer) in terms of records.
bIncludeStationInfo	int	Flag indicating whether station information should be retrieved along with the waveform descriptor information. The caller should set the value to TRUE if station (read component) information is desired, or to FALSE if it is not.
pWaveformDescsFound	int *	Pointer to an integer where the function will write the number of waveform descriptors found.
pWaveformDescsRetrieved	int *	Pointer to an integer where the function will write the number of waveform descriptors placed in the caller's buffer(pWaveformBuffer). If bIncludeStationInfo is set to TRUE by the caller, then the same number of EWDB_StationStructs will be written to pStationBuffer.

StartSnippetEvent

Prototype:

int StartSnippetEvent(

EWDBid * pidEvent, char * sSourceEventID, char * sAuthor, int Debug);

Description:

Function creates a new event in the DB, and returns the idEvent DB identifier for the new Event.

Note:

EWDB_StartSnippetEvent(), EWDB_NextSnippetForAnEvent() and EWDB_CloseSnippetEvent() are modeled after the Earthworm trace disposal routines for use with XXX_trace_save Earthworm programs like ora_trace_save, trig2disk, and waveman2disk. The logic behind the routines, is to call a StartEvent function to open the processing of an event. Next, NextSnippetForAnEvent is called repeatedly for all of the snippets associated with the event. Finally CloseEvent is called to end processing for an Event. Although 3 aforemention API functions support this processing model, they are not limited to it. The caller can thus call EWDB_NextSnippetForAnEvent() to add a snippet to a previous event. The caller does not have to call EWDB_StartSnippetEvent() before calling EWDB_NextSnippetForAnEvent(). As long as the caller provides a valid existing idEvent to EWDB_NextSnippetForAnEvent(), the call should function properly. A side effect of this functionality is that EWDB_CloseSnippetEvent() does nothing.

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
pidEvent	EWDBid *	A pointer to a EWDBid where the function will write The DB identifier of the Event it created.
sSourceEventID	char *	The identifier given to the Event by the author, in string format. This is an identifier external to the DB, not to be confused with idEvent which is the identifier given by the DB.
sAuthor	char *	The name of the author(source) of the new Event.
Debug	int	Flag indicating whether or not debug messages should be written to the log file. Set Debug to TRUE for debug log messages.

NextSnippetForAnEvent

Prototype:

int NextSnippetForAnEvent(

EWDBid idEvent, EWDB_EW_SnippetStruct * pSnippet, EWDBid * OUT_pidWaveform, EWDBid * INOUT_pidChan);

Description:

Function inserts a waveform snippet along with descriptor information, into the DB. It associates the snippet with the Event identified by idEvent. It returns the DB identifier of the new Waveform along with the DB identifier of the Waveform's associated channel.

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
idEvent	EWDBid	The database ID of an existing Event with which the caller wishes to associate a new waveform snippet.
pSnippet	EWDB_EW_SnippetStruct *	A pointer to waveform snippet structure, that includes parametric data describing a waveform snippet along with the actual waveform snippet.
OUT_pidWaveform	EWDBid *	A pointer to a EWDBid where the function will write The DB identifier of the waveform snippet it created.
INOUT_pidChan	EWDBid *	A pointer to a EWDBid where the function will write The DB channel identifier of the channel of the waveform snippet it created. If you already know the idChan for the channel of the snippet, you can set (INOUT_pidChan) to the proper idchan, otherwise WARNING!!!! (INOUT_pidChan) should be set to 0, or the function will attempt to treat it as a valid idchan.

ProcessSnippetReqs

Prototype:

int ProcessSnippetReqs(

char * szSta, char * szComp, char * szNet, char * szLoc, double tStart, double tEnd, EWDBid idEvent);

Description:

Added 2000/12/24 Function creates requests for snippets of waveform data for each channel that matches the given SCNL for the given time range. If idEvent is specified as non 0, then any snippets recovered as a result of the requests will be associated the given idEvent. *NOTE: This function does not retrieve any waveform data! It only creates requests for waveform data, that must be fulfilled by another program(concierge).

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

Parameter	Type	Description
szSta	char *	SEEDlike station code for the channel. It may not be blank or NULL, and should be a maximum of 7 characters.
szComp	char *	SEEDlike component code for the channel. The field may not be blank or NULL and should be a maximum of 9 characters. "*" may be used as a wildcard for this field.
szNet	char *	SEEDlike network code for the channel. It may not be blank or NULL and should be a maximum of 9 characters. "*" may be used as a wildcard for this field.
szLoc	char *	Optional SEEDlike location code for the channel. It should be a maximum of 9 characters. "*" may be used as a wildcard for this field.
tStart	double	The start of the time interval for which the caller wants a snippet for the given SCNL. Expressed as seconds since 1970.
tEnd	double	The end of the time interval for which the caller wants a snippet for the given SCNL. Expressed as seconds since 1970.
idEvent	EWDBid	The EWDB event identifer that the any resulting snippets should be associated with.

CloseSnippetEvent

Prototype:

int CloseSnippetEvent(

void);

Description:

Function is a do nothing placeholder routine that exists so the API waveform insertion routines(see note under EWDB_StartSnippetEvent) can resemble the Earthworm XXX_trace_save putaway routines.

Return Type:

int

Return Value	Description
EWDB_RETURN_SUCCESS	Success.