ewdb_api_DeleteSnippetRequest()

Prototype:

int ewdb_api_DeleteSnippetRequest(

EWDBid IN_idSnipReq, int IN_iLockTime);

Description:

The Function deletes the snippet request and any supporting information from the database.

RETURN CODE INFO

Return Type:

int

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

PARAMETER INFO

Parameter	Type	Description
IN_idSnipReq	EWDBid	DB ID of an existing SnippetRequest which the caller wishes to delete.
IN_iLockTime	int	The lock value of the given request. This should be the time the Request was locked. This value can be obtained via the EWDB_SnippetRequestStruct that was used in the call to lock the request. If the request is not locked, then this value is ignored.

Group:

EWDB_API_LIB

Sub Group:

WAVEFORM_REQUEST_API

Language:

Location:

./src/oracle/schema-working/src/include/ewdb_ora_api.h

ewdb_api_GetListOfOldSnipReqs()

Prototype:

int ewdb_api_GetListOfOldSnipReqs(

EWDB_SnippetRequestStruct * pBuffer, int iLockTimeThreshold, int * pNumItemsFound, int * pNumItemsRetrieved, int BufferLen);

Description:

THIS FUNCTION IS NOT FOR GENERAL CONSUMPTION. The function retrieves a list of snippet requests with OLD locks. It is for use by programs auditing the operation of the concierge system and should not be used in the mainstream processing of data.

Note:

THIS FUNCTION IS NOT FOR GENERAL CONSUMPTION. It is for auditing an problem detection. The function retrieves only the SCNL portion of the EWDB_SnippetRequestStruct.ComponentInfo.

RETURN CODE INFO

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 snippet requests was retrieved, but the caller's buffer was not large enough to accomadate all of the requests found. See pNumItemsFound for the number of arrivals found and pNumItemsRetrieved for the number of requests placed in the caller's buffer.

PARAMETER INFO

Parameter	Type	Description
pBuffer	EWDB_SnippetRequestStruct *	Buffer allocated by the caller, where the function will write the list of snippet requests that are active as of tThreshold.
iLockTimeThreshold	int	Threshold time for determining whether snippet requests are old or not. If the lock time of the request is earlier than iLockTimeThreshold, then the request is considered old. (Expressed as seconds since 1970)
pNumItemsFound	int *	Pointer to an integer where the function will write the number of snippet reuqests found.
pNumItemsRetrieved	int *	Pointer to an integer where the function will write the number of snippet requests placed in the caller's buffer(pBuffer).
BufferLen	int	Size of the pBuffer buffer as a multiple of EWDB_SnippetRequestStruct. (example: 15 structs)

Group:

EWDB_API_LIB

Sub Group:

WAVEFORM_REQUEST_API

Language:

Location:

./src/oracle/schema-working/src/include/ewdb_ora_api.h

ewdb_api_GetNextScheduledSnippetRetrievalAttempt()

Prototype:

int ewdb_api_GetNextScheduledSnippetRetrievalAttempt(

time_t * ptNextAttempt);

Description:

The function checks the snippet requests in the database to see when the next scheduled attempt is among all of the pending requests. The requests are schedule by the DB to be attempted at intervals. The function looks up the first scheduled attempt time.

RETURN CODE INFO

Return Type:

int

Return Value	Description
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.
EWDB_RETURN_WARNING	There were no pending snippet requests in the DB.

PARAMETER INFO

Parameter	Type	Description
ptNextAttempt	time_t *	Pointer to a time_t variable supplied by the caller where the function will write the next scheduled attempt time of all the pending snippet requests in the DB. (assuming that the function executes successfully and returns EWDB_RETURN_SUCCESS)

Group:

EWDB_API_LIB

Sub Group:

WAVEFORM_REQUEST_API

Language:

Location:

./src/oracle/schema-working/src/include/ewdb_ora_api.h

ewdb_api_GetSnippetRequestList()

Prototype:

int ewdb_api_GetSnippetRequestList(

EWDB_SnippetRequestStruct * pBuffer, time_t tThreshold, int iRequestGroup, int * pNumItemsFound, int * pNumItemsRetrieved, int BufferLen, EWDB_SnippetRequestStruct * IN_pSnipReq, int IN_bModifyAttemptParams, int IN_bModifyResultParams);

Description:

The function updates a snippet request. This function acts as a recording mechanism for the request processor. It allows the processor to record that it tried to retrieve a snippet, and it either got part or none of the desired snippet.
The function always updates the tNextAttempt time in the database with the value of IN_pSnipReq->tNextAttempt.
If IN_bModifyAttemptParams is true, then the DB updates the counter that track the number of attempts so far.
If IN_bModifyResultParams is true, then the DB will update tStart, tEnd, and idExistingWaveform if appropriate.

Note:

Set IN_pSnipReq->idExistingWaveform to 0 if a partial snippet was not retrieved. If a partial snippet was retrieved, first call ewdb_api_CreateWaveform() to store the snippet in the database, then call this function using the idWaveform that you got back from the create call.

RETURN CODE INFO

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 snippet requests was retrieved, but the caller's buffer was not large enough to accomadate all of the requests found. See pNumItemsFound for the number of arrivals found and pNumItemsRetrieved for the number of requests placed in the caller's buffer.
EWDB_RETURN_FAILURE	Fatal error. See logfile for details.
EWDB_RETURN_SUCCESS	Success.

PARAMETER INFO

Parameter	Type	Description
pBuffer	EWDB_SnippetRequestStruct *	Buffer allocated by the caller, where the function will write the list of snippet requests that are active as of tThreshold. If you want to retrieve a list of request, then you MUST initialize pBuffer[0].idSnipReq to 0. Otherwise, the function will only attempt to retrieve the one SnippetRequest identified by pBuffer[0].idSnipReq regardless of the other parameters.
tThreshold	time_t	Threshold time for determining whether snippet requests are active or not. If the next scheduled attempt for retrieving a snippet requests is earlier than tThreshold, then the request is considered active. Only active requests are returned, in increasing order of next scheduled attempt. (Expressed as seconds since 1970)
iRequestGroup	int	Request group for which the caller is interested in snippet requests. Set this to -1 to get all Snippet Requests regardless of Request Group. See EWDB_SnippetRequestStruct for a description of RequestGroup.
pNumItemsFound	int *	Pointer to an integer where the function will write the number of snippet reuqests found.
pNumItemsRetrieved	int *	Pointer to an integer where the function will write the number of snippet requests placed in the caller's buffer(pBuffer).
BufferLen	int	Size of the pBuffer buffer as a multiple of EWDB_SnippetRequestStruct. (example: 15 structs)
IN_pSnipReq	EWDB_SnippetRequestStruct *	Pointer to a EWDB_SnippetRequestStruct, where the caller puts the parameters of the SnippetRequest that they wish to update.
IN_bModifyAttemptParams	int	TRUE/FALSE flag indicating whether the attempt should be recorded. If true, the DB will increment the counter that tracks how many times the request has been attempted. (VERY SIMPLE)
IN_bModifyResultParams	int	TRUE/FALSE flag indicating whether or not any new snippet data was found, and thus whether the snippetrequest should be updated (new tStart or tEnd, idExistingWaveform).

Group:

EWDB_API_LIB

Sub Group:

WAVEFORM_REQUEST_API

Language:

Location:

./src/oracle/schema-working/src/include/ewdb_ora_api.h

ewdb_api_ProcessSnippetReqs()

Prototype:

int ewdb_api_ProcessSnippetReqs(

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

Description:

The Function creates a Snippet Request record in the DB, for the given time range, for each channel that matches the given SCNL codes. The record describes snippet data that the caller wants stored in the DB. (This call does not retrieve snippet data, it only records the request.) A snippet is essentially a piece of data from a given channel for a given time interval. 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. The requests must be handled by another program(concierge).

RETURN CODE INFO

Return Type:

int

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

PARAMETER INFO

Parameter	Type	Description
szSta	char *	SEEDlike Station code of the channels for which the caller wishes to create snippet requests. This param CANNOT be NULL or blank. Use the wildcard string "*" to match all possible Station codes.
szComp	char *	SEEDlike Component code of the channels for which the caller wishes to create snippet requests. This param CANNOT be NULL or blank. Use the wildcard string "*" to match all possible Component codes.
szNet	char *	SEEDlike Network code of the channels for which the caller wishes to create snippet requests. This param CANNOT be NULL or blank. Use the wildcard string "*" to match all possible Network codes.
szLoc	char *	SEEDlike Location code of the channels for which the caller wishes to create snippet requests. This param CANNOT be NULL. It may be blank(""). Use the wildcard string "*" to match all possible Location codes.
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.
iNumAttempts	int	The number of times that the caller wishes to have the request attempted. It is up to the data retriever to enforce/interpret this number.
iRequestGroup	int	The Request Group that the caller wishes the request associated with. Requests may be divided into groups for more efficient retrieval. This param may be later modified/ignored by the data retriever.

Group:

EWDB_API_LIB

Sub Group:

WAVEFORM_REQUEST_API

Language:

Location:

./src/oracle/schema-working/src/include/ewdb_ora_api.h

ewdb_api_UpdateSnippetRequestControlParams()

Prototype:

int ewdb_api_UpdateSnippetRequestControlParams(

EWDB_SnippetRequestStruct * IN_pSnipReq);

Description:

The function updates the control parameters for a snippet request. At this time, the control params are:
iNumAttempts(the number of times the request will attempt to be fulfilled), and
iRequestGroup(the request group in which the request has been categorized).

Note:

IN_pSnipReq->iLockTime must match the LockTime for the request (and the request must be locked). (You must lock the request before you can modify the control params and you must remember to unlock it afterwards.)

RETURN CODE INFO

Return Type:

int

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

PARAMETER INFO

Parameter	Type	Description
IN_pSnipReq	EWDB_SnippetRequestStruct *	Pointer to a EWDB_SnippetRequestStruct, where the caller puts the parameters of the SnippetRequest that they wish to update.

Group:

EWDB_API_LIB

Sub Group:

WAVEFORM_REQUEST_API

Language:

Location:

./src/oracle/schema-working/src/include/ewdb_ora_api.h