# 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.