Functions of the EW5 Oracle API

EWDB_OraAPIInit

Prototype:
int EWDB_OraAPIInit( char * DBuser, char * DBpassword, char * DBservice);
Description: Initialization function for the API. This function should be called prior to any other API calls. It initializes the API environment and validates the database connection parameters (DBuser, DBpassword, DBservice).
Return Type: int

Return Value Description
EWDB_RETURN_SUCCESS The API environment was successfully initialized.
EWDB_RETURN_FAILURE The API environment failed to initialize. Please see stderr or a logfile for details of the failure.
EWDB_RETURN_WARNING The API environment was already initialized. If the client needs to reinitialize the API environment with different parameters, they must first call EWDB_OraAPIShutdown to uninitialize the existing environment.

Parameter Type Description
DBuser char * The database user that the program should run as.
DBpassword char * The password for user DBuser.
DBservice char * The network serviceID of the database to connect to. In Oracle environments, the serviceID is usually defined in either a tnsnames.ora file or by an Oracle Names server.


EWDB_OraAPIShutdown

Prototype:
int EWDB_OraAPIShutdown( void);
Description: Shutdown the API environment and free any related memory and handles.
Return Type: int

Return Value Description
EWDB_RETURN_SUCCESS The API environment was successfully de-initialized.
EWDB_RETURN_FAILURE The API environment failed to de-initialize. Please see stderr or a logfile for details of the failure.
EWDB_RETURN_WARNING The API environment had not been initialized using EWDB_OraAPIInit.

ewdb_api_CreateArrival

Prototype:
int ewdb_api_CreateArrival( EWDB_ArrivalStruct * pArrival);
Description: Function creates an arrival from the caller supplied information in pArrival. The function assumes that the caller has supplied all information for an arrival including origin-phase information. The pArrival->idOrigin must be a valid existing origin DB ID. Upon successful completion, the function writes the DB ID of the newly created phase pick(Pick) and the newly created OriginPick to pArrival->idPick and pArrival->idOriginPick respectively.
Return Type: int

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

Parameter Type Description
pArrival EWDB_ArrivalStruct * Pointer to a EWDB_ArrivalStruct filled by the caller.


ewdb_api_CreateBodyAmp

Prototype:
int ewdb_api_CreateBodyAmp( EWDB_PhaseAmpStruct * pBodyAmp, 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
EWDB_RETURN_FAILURE Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS Success.

Parameter Type Description
pBodyAmp EWDB_PhaseAmpStruct * Pointer to the PhaseAmp structure filled with the information to be inserted into the DB.
pDurCoda EWDB_PhaseAmpStruct * Pointer to a EWDB_PhaseAmpStruct filled by the caller.


ewdb_api_CreateEvent

Prototype:
int ewdb_api_CreateEvent( EWDB_EventStruct * pEvent);
Description: Function creates an event in the DB using the information provided by the caller in pEvent. Upon successful completion, the function writes the DB ID of the newly created event to pEvent->idEvent.
Return Type: int

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

Parameter Type Description
pEvent EWDB_EventStruct * Pointer to an EWDB_EventStruct filled by the caller.


ewdb_api_CreateMagnitude

Prototype:
int ewdb_api_CreateMagnitude( EWDB_MagStruct * pMag);
Description: Function creates a magnitude in the DB using the information provided by the caller in pMag. If pMag->BindToEvent is set to TRUE, then the function will attempt to associate the new magnitude with an existing event(pMag->idEvent). If both pMag->BindToEvent and pMag->SetPreferred are TRUE, then the function will attempt to set the magnitude as the preferred one for the Event. Upon successful completion, the function writes the DB ID of the newly created magnitude to pMag->idMag.
Return Type: int

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

Parameter Type Description
pMag EWDB_MagStruct * Pointer to an EWDB_MagStruct filled by the caller.


ewdb_api_CreateOrigin

Prototype:
int ewdb_api_CreateOrigin( EWDB_OriginStruct * pOrigin);
Description: Function creates an origin in the DB using the information provided by the caller in pOrigin. If pOrigin->BindToEvent is set to TRUE, then the function will attempt to associate the new origin with an existing event(pOrigin->idEvent). If both pOrigin->BindToEvent and pOrigin->SetPreferred are TRUE, then the function will attempt to set the origin as the preferred one for the Event. Upon successful completion, the function writes the DB ID of the newly created origin to pOrigin->idOrigin.
Return Type: int

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

Parameter Type Description
pOrigin EWDB_OriginStruct * Pointer to an EWDB_OriginStruct filled by the caller.


ewdb_api_CreateStaMag

Prototype:
int ewdb_api_CreateStaMag( EWDB_PhaseAmpStruct * pBodyAmp);
Description: Inserts the information from the PhaseAmp structure into the database.
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 * PhaseAmp structure filled by the caller


ewdb_api_CreateTCoda

Prototype:
int ewdb_api_CreateTCoda( EWDB_PhaseAmpStruct * pTCoda);
Description: Inserts the information about the coda from the PhaseAmp structure into the database.
Return Type: int

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

Parameter Type Description
pTCoda EWDB_PhaseAmpStruct * PhaseAmp structure filled by the caller.


ewdb_api_DeleteEvent

Prototype:
int ewdb_api_DeleteEvent( int IN_idEvent, int IN_bDeleteTraceOnly);
Description: Deletes trace and/or parametric data for an event from the database. Note that this means that the deleted data is permanently gone.
Return Type: int

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

Parameter Type Description
IN_idEvent int DB id of the event to delete.
IN_bDeleteTraceOnly int If set to 1, delete only trace, otherwise delete both trace and parametric data for this event.


ewdb_api_GetArrivals

Prototype:
int ewdb_api_GetArrivals( EWDBid idOrigin, EWDB_ArrivalStruct * pArrivals, int * pNumArrivalsFound, int * pNumArrivalsRetrieved, int BufferLen);
Description: The function retrieves a list of arrivals that are associated with a given origin. See EWDB_ArrivalStruct for a description of the information retrieved for each associated arrival.
Return Type: int

Return Value Description
EWDB_RETURN_FAILURE Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS Success.
EWDB_RETURN_WARNING Partial success. A list of arrivals was retrieved, but the caller's buffer was not large enough to accomadate all of the arrivals found. See pNumArrivalsFound for the number of arrivals found and pNumArrivalsRetrieved for the number of arrivals placed in the caller's buffer.

Parameter Type Description
idOrigin EWDBid This function retrieves a list of arrivals associated with an origin. idOrigin is the database ID of the origin for which the caller wants a list of arrivals.
pArrivals EWDB_ArrivalStruct * Buffer allocated by the caller, where the function will write the list of arrivals.
pNumArrivalsFound int * Pointer to an integer where the function will write the number of found arrivals.
pNumArrivalsRetrieved int * Pointer to an integer where the function will write the number of arrivals placed in the callers buffer(pArrivals).
BufferLen int Size of the pArrivals buffer as a multiple of EWDB_ArrivalStruct. (example: 15 structs)


ewdb_api_GetEventInfo

Prototype:
int ewdb_api_GetEventInfo( EWDBid idEvent, EWDB_EventStruct * pEvent);
Description: Function retrieves information about the Event identified by idEvent. See EWDB_EventStruct for a description of the information provided.
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 information.
pEvent EWDB_EventStruct * Pointer to a EWDB_EventStruct allocated by the caller, where the function will write the information about the Event.


EWDB_GetEventList

Prototype:
int EWDB_GetEventList( EWDB_EventListStruct * pBuffer, int len, int StartTime, int EndTime, EWDB_EventListStruct * pCriteria, EWDB_EventListStruct * pMaxEvent, int * pNumEvents);
Description: Returns the list of all events in the database, in a given time range, that meet the criteria specified in pCriteria.
Return Type: int

Return Value Description
EWDB_RETURN_SUCCESS A list of events was successfully retrieved.
EWDB_RETURN_FAILURE The function experienced a fatal error while retrieving a list of events.
-x < -1 (-x) is returned where x > 1 when the size of the caller's buffer is insufficient to hold all of the events that matched the caller's criteria. x is the size of the buffer required to retrieve all of the events that were found. The function places as many events as possible into the caller's existing buffer. This is not a failure condition, just a warning that the caller did not receive all of the requested data.

Parameter Type Description
pBuffer EWDB_EventListStruct * Buffer allocated by the caller, in which the function will place the list of events matching the caller's criteria.
len int Length of pBuffer as a multiple of EWDB_EventListStruct.
StartTime int Minimum(oldest) time acceptable for an event. Expressed as seconds since 1970(time_t).
EndTime int Maximum(youngest) time acceptable for an event. Expressed as seconds since 1970(time_t).
pCriteria EWDB_EventListStruct * Pointer to the EWDB_EventListStruct that contains part of the selection criteria for the list, including: minimum lattitude, minimum longitude, minimum depth, minimum magnitude, and source limitations. Source criteria is:
"*" events from all sources
"**" events from only human sources
"" (blank string)all automatic sources
Any other string will be matched against the source identifier, such as the logo of the earthworm module that created a solution, or the dblogin of a human reviewer.
pMaxEvent EWDB_EventListStruct * Pointer to the EWDB_EventListStruct that contains part of the selection criteria for the list, including: maximum lattitude, maximum longitude, maximum depth, and maximum magnitude.
pNumEvents int * Pointer to an integer where the function writes the number of events it put in pBuffer.


ewdb_api_GetMagnitude

Prototype:
int ewdb_api_GetMagnitude( EWDBid idMag, EWDB_MagStruct * pMag);
Description: Function retrieves information about the Magnitude identified by idMag. See EWDB_MagStruct for a description of the information provided.
Return Type: int

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

Parameter Type Description
idMag EWDBid The DB identifier of the Magnitude for which the caller wants information.
pMag EWDB_MagStruct * Pointer to a EWDB_MagStruct allocated by the caller, where the function will write the information about the Magnitude.


ewdb_api_GetOrigin

Prototype:
int ewdb_api_GetOrigin( EWDBid idOrigin, EWDB_OriginStruct * pOrigin);
Description: Function retrieves information about the Origin identified by idOrigin. See EWDB_OriginStruct for a description of the information provided.
Return Type: int

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

Parameter Type Description
idOrigin EWDBid The DB identifier of the Origin for which the caller wants information.
pOrigin EWDB_OriginStruct * Pointer to a EWDB_OriginStruct allocated by the caller, where the function will write the information about the Origin.


ewdb_api_GetPreferredSummaryInfo

Prototype:
int ewdb_api_GetPreferredSummaryInfo( EWDBid idEvent, EWDBid * pidOrigin, EWDBid * pidMagnitude, EWDBid * pidMech);
Description: Function retrieves the DB IDs for the preferred summary information(origin, magnitude, and mechanism) for 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 for the Event for which the caller wants summary info.
pidOrigin EWDBid * Pointer to a EWDBid where the function will write the DB ID of the preferred origin for the Event. 0 will be written as the ID if there is no preferred origin for the given Event.
pidMagnitude EWDBid * Pointer to a EWDBid where the function will write the DB ID of the preferred magnitude for the Event. 0 will be written as the ID if there is no preferred magnitude for the given event.
pidMech EWDBid * Pointer to a EWDBid where the function will write the DB ID of the preferred mechanism for the Event. 0 will be written as the ID if there is no preferred mechanism for the given event. (Note: Mechanism are currently only supported in a trivial manner)


ewdb_api_GetStaMags

Prototype:
int ewdb_api_GetStaMags( EWDBid idMagnitude, EWDB_StationMagnitudeStruct * pStaMags, int * pNumStaMagsFound, int * pNumStaMagsRetrieved, char * szMagType, int BufferLen);
Description: The function retrieves a list of station magnitudes that are associated with a given summary magnitude. See EWDB_StationMagnitudeStruct for a description of the information retrieved for each associated station magnitude.
Return Type: int

Return Value Description
EWDB_RETURN_FAILURE Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS Success.
EWDB_RETURN_WARNING Partial success. A list of station magnitudes was retrieved, but the caller's buffer was not large enough to accomadate all of the station magnitudes found. See pNumStaMagsFound for the number of station magnitudes found and pNumStaMagsRetrieved for the number of station magnitudes placed in the caller's buffer.

Parameter Type Description
idMagnitude EWDBid This function retrieves a list of station magnitudes associated with an summary magnitude. idMagnitude is the database ID of the magnitude for which the caller wants a list of station magnitudes.
pStaMags EWDB_StationMagnitudeStruct * Buffer allocated by the caller, where the function will write the list of station magnitudes.
pNumStaMagsFound int * Pointer to an integer where the function will write the number of station magnitudes found.
pNumStaMagsRetrieved int * Pointer to an integer where the function will write the number of station magnitudes placed in the caller's buffer(pStaMags).
szMagType char * The type of magnitude for which to retrieve information. This is a screwed up parameter, because this should be retrieved from the DB based on idMagnitude. However, in their infinite wisdom, the writer(s) of this function decided to make it a parameter. Enter "DurCoda" if the magnitude is a duration magnitude. Enter "AmpBody" if the magnitude is an amplitude magnitude(such as ML) even if it is a surface wave based magnitude. CLEANUP!
BufferLen int Size of the pArrivals buffer as a multiple of EWDB_ArrivalStruct. (example: 15 structs)


ewdb_api_UpdateComment

Prototype:
int ewdb_api_UpdateComment( char * szFieldTypeName, EWDBid idCore, char * szUpdatedComment);
Description: Updates a comment for any record in the DB. Enter the tablename and the record ID for the table that the comment belongs to, and the function will update the comment for that record. This requires that the caller know DB layout, which is a bad thing. What we need is a lookup table for the comment types, and we can perform a conversion from the lookup table to the actual DB table type withing the DB.
Return Type: int

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

Parameter Type Description
szFieldTypeName char * Name of the table to updated
idCore EWDBid id of the record to update
szUpdatedComment char * Text of the updated comment.


ewdb_api_CreateOrAlterExternalStation

Prototype:
int ewdb_api_CreateOrAlterExternalStation( 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 External Station to pStation->StationID. 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.


ewdb_api_GetIdChanFromStationExternal

Prototype:
int ewdb_api_GetIdChanFromStationExternal( EWDBid * pidChan, int StationID);
Description: Given the DB id of the external station, find and return the idChan for it.
Return Type: int

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

Parameter Type Description
pidChan EWDBid * Output idChan for this external station.
StationID int Database id of the external station.


ewdb_api_CreateSnippet

Prototype:
int ewdb_api_CreateSnippet( EWDBid IN_idWaveform, char * IN_pSnippet, int IN_SnippetSize);
Description: Insert the binary waveform snippet into the database.
Return Type: int

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

Parameter Type Description
IN_idWaveform EWDBid Database ID of the Waveform associated with this snippet.
IN_pSnippet char * Pointer to the binary waveform snippet to be inserted.
IN_SnippetSize int Length of the snippet.


ewdb_api_CreateWaveformDesc

Prototype:
int ewdb_api_CreateWaveformDesc( EWDB_WaveformStruct * pWaveform, int bBindToEvent, EWDBid idEvent);
Description: Insert a waveform descriptor record into the database and associate it with an Event if bBindToEvent is set to 1.
Return Type: int

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

Parameter Type Description
pWaveform EWDB_WaveformStruct * Input waveform structure filled by the caller.
bBindToEvent int Set to 1 if this waveform record should be bound to the event specified by idEvent.
idEvent EWDBid Database ID of the Event with which this Waveform Descriptor is associated.


ewdb_api_GetWaveformDesc

Prototype:
int ewdb_api_GetWaveformDesc( EWDB_WaveformStruct pWaveformDesc);
Description: Retrieve information about the waveform descriptor pointed to by pWaveformDesc->idWaveform from the database.
Return Type: int

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

Parameter Type Description
pWaveformDesc EWDB_WaveformStruct Structure holding output information about the waveform descriptor retrieved from the database.


ewdb_api_GetWaveformList

Prototype:
int ewdb_api_GetWaveformList( EWDBid IN_idEvent, EWDB_WaveformStruct IN_pWaveformBuffer, int IN_BufferRecLen);
Description: Returns the array of waveform structs, one for each waveform entry in the database associated with the Event.
Return Type: int

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

Parameter Type Description
IN_idEvent EWDBid Database ID of the Event whose waveform snippets we are interested in.
IN_pWaveformBuffer EWDB_WaveformStruct Pointer to a pre-allocated array of waveform structs which will be filled by this function.
IN_BufferRecLen int Length of the IN_pWaveformBuffer array.


ewdb_api_GetWaveformListWithCompT> ewdb_api_GetWaveformListWithCompT

Prototype:
int ewdb_api_GetWaveformListWithCompT( EWDBid IN_idEvent, EWDB_WaveformStruct IN_pWaveformBuffer, EWDB_StationStruct IN_pStationBuffer);
Description: UNKNOWN
Return Type: int

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

Parameter Type Description
IN_idEvent EWDBid UNKNOWN
IN_pWaveformBuffer EWDB_WaveformStruct UNKNOWN
IN_pStationBuffer EWDB_StationStruct UNKNOWN


ewdb_api_GetWaveformSnippet

Prototype:
int ewdb_api_GetWaveformSnippet( EWDBid IN_idWaveform, char * IN_pWaveform, int IN_WaveformLength);
Description: Retrieves the snippet associated with IN_idWaveform and returns it in the IN_pWaveform buffer.
Return Type: int

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

Parameter Type Description
IN_idWaveform EWDBid Database ID of the waveform descriptor whose snippet we are interested in.
IN_pWaveform char * Preallocated buffer to hold the output snippet.
IN_WaveformLength int Length of the IN_pWaveform buffer.


ewdb_api_AssociateChanWithComp

Prototype:
int ewdb_api_AssociateChanWithComp( EWDBid idComp, EWDBid idChan, double tStart, double tEnd, EWDBid * pidCompT, EWDBid * pidChanT);
Description: Function creates an association between a channel and a component for a specified time interval. The function can fail if a relationship exists between the specified component and an alternative channel, or between the specified channel and an alternative component, during an overlapping time period.
Note: The relationship between a component and a channel is complex to implement. I believe the issues that cause the pidCompT and pidChanT variables to be written to, have been cleared up, and they are no longer applicable; however, I am not sure of this, so please be sure to pass valid pointers until better documentation can be made available. davidk 2000/05/04.
The following is believed to be out of date, but is the best information available at this time:
A channel can be associated with at most one component at a given time. If the channel that the caller is trying to bind a component to is already bound to another component during an overlapping time interval, then the call will fail, and the idComp of the first component found that has an overlapping association with that channel will be returned. Currently, if there are any existing chan relationships during the time period described by tStart,tEnd, for the given idChan, then the idChanT of the first ChanT relationship record will be returned in pidChanT along with an error condition.

Is this function even used anymore????? How is it different than EWDB_SetChanParams?
Return Type: int

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

Parameter Type Description
idComp EWDBid The DB identifier of the component(Comp) record the caller wants to associate with a channel.
idChan EWDBid The DB identifier of the channel(Chan) record the caller wants to associate with a component.
tStart double The start of the time interval for which the caller wants to associate the component and channel. Expressed as seconds since 1970.
tEnd double The end of the time interval for which the caller wants to associate the component and channel. Expressed as seconds since 1970.
pidCompT EWDBid * A pointer to a EWDBid where the function will write information if the call fails.
pidChanT EWDBid * A pointer to a EWDBid where the function will write information if the call fails.


ewdb_api_CreateChannel

Prototype:
int ewdb_api_CreateChannel( EWDBid * pidChan, char * szComment);
Description: Function creates a channel in the DB. A channel identifies the entire path of a seismic signal from ground motion to completed waveform. The function writes the DB ID of the newly created channel to pidChan. Because most of a channel's properties are variable over time, this function does not take much as input, as it only creates a channel with its fixed attribute(s). This function should be used to generate a new idChan that can be used in conjunction with other functions for creating components and setting time based attributes of components and channels.
Note: A channel(Chan) represents a unique data path from ground motion to finished waveform. It is associated with a Component sensor, and all of the signal altering devices that the sensor's signal passes through before becoming a finished set of waveforms.
Return Type: int

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

Parameter Type Description
pidChan EWDBid * A pointer to a EWDBid where the function will write The DB identifier of the Channel it created.
szComment char * Optional comment regarding the component. It may be blank, and should be a maximum of 4k characters. It may not be NULL!


ewdb_api_CreateCompTForSCNLT

Prototype:
int ewdb_api_CreateCompTForSCNLT( EWDBid * pidChan, char * szSta, char * szComp, char * szNet, char * szLoc, double tStart, double tEnd);
Description: UNKNOWN
Return Type: int

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

Parameter Type Description
pidChan EWDBid * UNKNOWN
szSta char * UNKNOWN
szComp char * UNKNOWN
szNet char * UNKNOWN
szLoc char * UNKNOWN
tStart double UNKNOWN
tEnd double UNKNOWN


ewdb_api_CreateComponent

Prototype:
int ewdb_api_CreateComponent( EWDBid * pidComp, char * sSta, char * sComp, char * sNet, char * sLoc, char * szComment);
Description: Function creates a component sensor in the DB with an SCN and optionally L. It associates the component with a site identified by (Sta,Net). It returns the DB ID of the newly created component. If a component already exists with the specified SCNL, then a new component is not created and the idComp of the existing component is returned.
Note: A component(Comp) represents a seismic sensor in the field. It is represented by SCN and optionaly L, and has location properties(Lat,Lon, and Elev) and orientation properties(Azimuth and Dip).
Return Type: int

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

Parameter Type Description
pidComp EWDBid * A pointer to a EWDBid where the function will write The DB identifier of the Component it created.
sSta char * SEEDlike station code for the Component. It may not be blank or NULL, and should be a maximum of 7 characters.
sComp char * SEEDlike component code for the Component. The field may not be blank or NULL and should be a maximum of 9 characters.
sNet char * SEEDlike network code for the Component. It may not be blank or NULL and should be a maximum of 9 characters.
sLoc char * Optional SEEDlike location code for the component. It may not be blank or NULL and should be a maximum of 9 characters.
szComment char * Optional comment regarding the component. May be blank, and should be a maximum of 4k characters. It may not be NULL!


ewdb_api_CreateTransformFunction

Prototype:
int ewdb_api_CreateTransformFunction( EWDBid * pidCookedTF, EWDB_TransformFunctionStruct * pCookedTF);
Description: Function inserts a caller provided poles/zeroes based transform function into the DB. The transform Function is used to transform recorded waveforms back into ground motion. The function writes the DB id of the newly created transform function to pidCookedTF.
Note: The transform function can be associated with multipe channel time intervals using EWDB_SetTransformFuncForChanT().
Return Type: int

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

Parameter Type Description
pidCookedTF EWDBid * Pointer to a EWDBid where the function will write the DB ID of the newly created poles and zeroes based cooked transform function(CookedTF).
pCookedTF EWDB_TransformFunctionStruct * Pointer to a caller filled EWDB_TransformFunctionStruct that contains the transform function and associated information that the caller wants to insert into the DB.


ewdb_api_GetChanCTFForChannel

Prototype:
int ewdb_api_GetChanCTFForChannel( EWDB_ChanTCTFStruct * pChanCTF);
Description: Function retrieves the gain, sample rate, and ID of the poles and zeroes based transform function, for a give channel time interval identified by pChanCTF->idChanT.
Note: This function should not be exposed as part of the API, unless someone can think of a really good reason. It is currently called by EWDB_GetTransformFunctionForChan(), which provides the actual transform function as well as the gain and sample rate.
Return Type: int

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

Parameter Type Description
pChanCTF EWDB_ChanTCTFStruct * Pointer to a caller allocated EWDB_ChanTCTFStruct. The function will read the idChanT(channel time interval identifier) from the struct, and then write the gain(dGain), sample rate(dSampRate), and cooked transform function identifier(idCookedTF) associated with the given idChanT.


ewdb_api_GetComponentInfo

Prototype:
int ewdb_api_GetComponentInfo( EWDBid idChan, int tParamsTime, EWDB_StationStruct * pStation);
Description: Function retrieves a EWDB_StationStruct full of information about the component associated with a channel at a give time.
Note: The following serious errors are ignored by the function.
-2 ChanT record not found for given time/idchan
-3 CompT record not found for ChanT record
-4 Unknown NO_DATA_FOUND error
CLEANUP!!!!
The function will return EWDB_RETURN_SUCCESS even if these errors occur. The only way the caller can check for these error conditions is to check the value of pStation->idComp after completion of the function. If the value is 0, the function should be treated as if it experienced a fatal error and all data returned is invalid.
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 identifier of the channel for which the caller wants information.
tParamsTime int Point in time for which the caller wants component parameter information. A time is required because some parameters are variable over time.
pStation EWDB_StationStruct * A pointer to a EWDB_StationStruct where the function will write the component parameter information for the given channel and time.


ewdb_api_GetStationList

Prototype:
int ewdb_api_GetStationList( double MinLat, double MaxLat, double MinLon, double MaxLon, double ReqTime, EWDB_StationStruct * pBuffer, int len, int * pNumStations);
Description: This function retrieves a list of component/channels given a lat/lon box and time of interest. Component attributes for the given time are included.(Lat,Lon,etc.) (MinLat,MinLon) and (MaxLat,MaxLon) define two vertices(?) of a box. The function retrieves the list of stations within the box. (Be careful of the effects of negative Lat/Lon on Min/Max!!)
Return Type: int

Return Value Description
EWDB_RETURN_FAILURE Returned when the caller passes an invalid set of criteria.
EWDB_RETURN_SUCCESS Success.
-x < -1 (-x) is returned where x > 1 when the size of the caller's buffer is insufficient to hold all of the stations that matched the caller's criteria. x is the size of the buffer required to retrieve all of the stations that were found. The function places as many stations as possible into the caller's existing buffer. This is not a failure condition, just a warning that the caller did not receive all of the requested data.

Parameter Type Description
MinLat double Minimum lattitude coordinate of stations to be retrieved. Lattitude is expressed in degrees.
MaxLat double Maximum lattitude coordinate of stations to be retrieved. Lattitude is expressed in degrees.
MinLon double Minimum longitude coordinate of stations to be retrieved. Longitude is expressed in degrees.
MaxLon double Maximum longitude coordinate of stations to be retrieved. Longitude is expressed in degrees.
ReqTime double Time of interest. The list of active components changes over time. Reqtime identifies the historical point it time for which the caller wants a station list. Time is expressed in seconds since 1970.
pBuffer EWDB_StationStruct * Buffer allocated by the caller, in which the function will place the list of stations matching the caller's criteria.
len int Length of pBuffer as a multiple of EWDB_StationStruct.
pNumStations int * Pointer to an integer where the function will write the number of stations it wrote to pBuffer.


ewdb_api_GetStationListWithoutLocation> ewdb_api_GetStationListWithoutLocation

Prototype:
int ewdb_api_GetStationListWithoutLocation( double ReqTime, EWDB_StationStruct * pBuffer, int len, int * pNumStations);
Description: This function retrieves a list of component/channels given a time of interest. Component attributes for the given time are included.(Lat,Lon,etc.) This effectively pulls component information for every channel in the database (it only pulls for the channels that were valid at time ReqTime). This query may return over 4000 rows!
Return Type: int

Return Value Description
EWDB_RETURN_FAILURE Returned when the caller passes an invalid set of criteria.
EWDB_RETURN_SUCCESS Success.
-x < -1 (-x) is returned where x > 1 when the size of the caller's buffer is insufficient to hold all of the stations that matched the caller's criteria. x is the size of the buffer required to retrieve all of the stations that were found. The function places as many stations as possible into the caller's existing buffer. This is not a failure condition, just a warning that the caller did not receive all of the requested data.

Parameter Type Description
ReqTime double Time of interest. The list of active components changes over time. Reqtime identifies the historical point it time for which the caller wants a station list. Time is expressed in seconds since 1970.
pBuffer EWDB_StationStruct * Buffer allocated by the caller, in which the function will place the list of stations matching the caller's criteria.
len int Length of pBuffer as a multiple of EWDB_StationStruct.
pNumStations int * Pointer to an integer where the function will write the number of stations it wrote to pBuffer.


ewdb_api_GetTransformFunction

Prototype:
int ewdb_api_GetTransformFunction( EWDBid idCookedTF, EWDB_TransformFunctionStruct * pCookedTF);
Description: Function retrieves the poles/zeroes based transform function identified by idCookedTF from the DB. The transform Function is used to transform recorded waveforms back into ground motion.
Note: Call EWDB_GetTransformFunctionForChan() to retrieve the transform function for a given channel along with gain and sample rate.
Return Type: int

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

Parameter Type Description
idCookedTF EWDBid The DB ID of the cooked transform function that the caller wants to retrieve.
pCookedTF EWDB_TransformFunctionStruct * Pointer to a caller allocated EWDB_TransformFunctionStruct where the function will write the cooked transform function requested by the caller.


ewdb_api_GetTransformFunctionDesc> ewdb_api_GetTransformFunctionDesc

Prototype:
int ewdb_api_GetTransformFunctionDesc( EWDBid idCookedTF, char * szCookedTFDesc, EWDBid idChan, double tTime, EWDBid * pidChanT);
Description: Function retrieves the identifier of the channel time interval associated with the given channel and time.
Return Type: int

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

Parameter Type Description
idCookedTF EWDBid Database ID for the cooked infrastructure record.
szCookedTFDesc char * Output description for this record.
idChan EWDBid The DB identifier of the channel for which the caller wants a channel time interval(ChanT) identifier.
tTime double Point in time for which the caller wants a time interval identifier for the channel.
pidChanT EWDBid * A pointer to a EWDBid where the function will write The DB identifier of the requested channel time interval(ChanT).


ewdb_api_GetidChansFromSCNLT

Prototype:
int ewdb_api_GetidChansFromSCNLT( EWDBid * pBuffer, int BufferRecLen, char * szSta, char * szComp, char * szNet, char * szLoc, double * tOff, double * tOn, int * pNumIDChans);
Description: UNKNOWN
Return Type: int

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

Parameter Type Description
pBuffer EWDBid * UNKNOWN
BufferRecLen int UNKNOWN
szSta char * UNKNOWN
szComp char * UNKNOWN
szNet char * UNKNOWN
szLoc char * UNKNOWN
tOff double * UNKNOWN
tOn double * UNKNOWN
pNumIDChans int * UNKNOWN


ewdb_api_SetChanParams

Prototype:
int ewdb_api_SetChanParams( EWDBid idChan, double tOn, double tOff, EWDBid idCompT, EWDBid idDevice, EWDBid * pidChanT, char * szComment);
Description: Function sets the variable parameters of a channel for a given time interval. Variable parameters include the starting device in the channel in the waveforms to ground motion direction, and the component that the channel is associated with. The function will write the DB ID of the newly created/updated channel time interval record to to pidChanT.
Note: idDevice is currently ignored due to a lack of infrastructure schema. Please set the value to 0.
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 the caller wants to set parameters for.
tOn double The start of the time interval for which the caller wants the channel parameters to be valid. Expressed as seconds since 1970.
tOff double The end of the time interval for which the caller wants the channel parameters to be valid. Expressed as seconds since 1970.
idCompT EWDBid The DB ID of the component time interval(CompT) that the caller wants to associate with the channel. CLEANUP! Shouldn't the caller specify a component and the DB logic determin the CompT by Comp and Time???
idDevice EWDBid The DB ID of the first device in the channel(in order of finished waveforms -> ground motion).
pidChanT EWDBid * A pointer to a EWDBid where the function will write the DB ID of the updated or newly created channel tme interval(ChanT).
szComment char * Optional comment regarding the channel time interval(ChanT). It may be blank, and should be a maximum of 4k characters. It may not be NULL!


ewdb_api_SetCompParams

Prototype:
int ewdb_api_SetCompParams( EWDB_StationStruct * pStation, double tOn, double tOff, EWDBid * pidCompT, char * szComment);
Description: Function sets the variable parameters of a component for a given time interval. Variable parameters include (lat,lon), elevation, and the orientation of the component. It will write the DB ID of the newly created/updated Component Time Interval record to to pidCompT.
Return Type: int

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

Parameter Type Description
pStation EWDB_StationStruct * Pointer to a EWDB_StationStruct that contains the parameters that the caller wishes to set for the component for the given time interval.
tOn double The start of the time interval for which the caller wants to the component parameters to be valid. Expressed as seconds since 1970.
tOff double The end of the time interval for which the caller wants to the component parameters to be valid. Expressed as seconds since 1970.
pidCompT EWDBid * A pointer to a EWDBid where the function will write the DB ID of the updated or newly created Component Time Interval.
szComment char * Optional comment regarding the Component Time Interval. It may be blank, and should be a maximum of 4k characters. It may not be NULL!


ewdb_api_SetTransformFuncForChanT

Prototype:
int ewdb_api_SetTransformFuncForChanT( EWDBid idChanT, double dGain, EWDBid idCookedTF, double dSampRate);
Description: Function associates an existing transform function with a Channel for a given time period. Records the gain and sample-rate that are specific to the channel.
Note: If you wish to create a transform function and associate it with a channel, you must first call EWDB_CreateTransformFunction() to create the channel. Then call EWDB_SetTransformFuncForChanT() using the idCookedTF that you got back from the create call.
Return Type: int

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

Parameter Type Description
idChanT EWDBid The DB identifier of the channel time interval(ChanT) with which the caller wants to associate a Poles and Zeroes transform function(CookedTF).
dGain double The signal gain for the channel time interval. Expressed as a double floating point multiplicative scalar.
idCookedTF EWDBid The DB identifier of the existing poles and zeroes based cooked transfer function, that the caller wants to associate with a given channel time interval(ChanT).
dSampRate double Digital sample rate of the data spouted out of the channel. Expressed as samples per second.


Raw_Infrastructure_Schema

Prototype:
Raw_Infrastructure_Schema( void);
Description: WORK IN PROGRESS: prototypes not yet finalized
Return Type:

Concierge_Schema

Prototype:
Concierge_Schema( void);
Description: WORK IN PROGRESS: prototypes not yet finalized
Return Type:

Strong_Motion_Schema

Prototype:
Strong_Motion_Schema( void);
Description: WORK IN PROGRESS: prototypes not yet finalized
Return Type: