source: trunk/include/ewdb_ora_api_strong_motion.h @ 5054

Revision 3471, 13.1 KB checked in by paulf, 9 years ago (diff)

oracle surgery additions

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1
2/*
3 *   THIS FILE IS UNDER RCS - DO NOT MODIFY UNLESS YOU HAVE
4 *   CHECKED IT OUT USING THE COMMAND CHECKOUT.
5 *
6 *    $Id$
7 *
8 *    Revision history:
9 *     $Log$
10 *     Revision 1.1  2008/12/02 21:37:42  paulf
11 *     oracle surgery additions
12 *
13 *     Revision 1.2  2004/09/09 17:21:10  davidk
14 *     Added ewdb_api_Delete* function protototypes.
15 *
16 *     Revision 1.1  2003/05/20 20:57:10  lucky
17 *     Initial revision
18 *
19 *
20 *
21 */
22
23
24/*******************************************************
25 *
26 * This include file contains only the structure
27 * definitions and function prototypes for the strong
28 * motion subschema.   
29 *
30 * This file should never be included in an application
31 * program.  Instead, include the master include file
32 * ewdb_ora_api.h
33 *
34 *    Lucky Vidmar, May 20, 2003
35 *
36 *******************************************************/
37
38#ifndef _EWDB_ORA_API_STRONG_MOTION_H
39#define _EWDB_ORA_API_STRONG_MOTION_H
40
41
42/**********************************************************
43 #########################################################
44    Struct Definition Section
45 #########################################################
46**********************************************************/
47
48
49/************************************************
50************ SPECIAL FORMATTED COMMENT **********
51EW5 API FORMATTED COMMENT
52TYPE TYPEDEF
53
54LIBRARY  EWDB_API_LIB
55
56SUB_LIBRARY STRONG_MOTION_API
57
58LANGUAGE C
59
60LOCATION THIS_FILE
61
62TYPEDEF EWDB_SMChanAllStruct
63TYPE_DEFINITION struct _EWDB_SMChanAllStruct
64DESCRIPTION This struct contains information for
65a single strong motion message(SMMessage), including
66any associated data, such as idEvent, Channel data.
67It is used to retrieve SMMessages from the DB.
68
69MEMBER idSMMessage
70MEMBER_TYPE EWDBid
71MEMBER_DESCRIPTION The DB ID of the SMMessage.
72
73MEMBER idSMMessage
74MEMBER_TYPE EWDBid
75MEMBER_DESCRIPTION The DB ID of the Event with which
76the message is associated.
77
78MEMBER Station
79MEMBER_TYPE EWDB_StationStruct
80MEMBER_DESCRIPTION A structure containing information
81about the channel from which the message was generated.
82
83MEMBER SMChan
84MEMBER_TYPE SM_INFO
85MEMBER_DESCRIPTION The strong motion message itself,
86in SM_INFO form.
87
88*************************************************
89************************************************/
90typedef struct _EWDB_SMChanAllStruct
91{
92  EWDBid idSMMessage;
93  EWDBid idEvent;
94  EWDB_StationStruct Station;
95  SM_INFO SMChan;
96} EWDB_SMChanAllStruct;
97
98
99/**********************************************************
100 #########################################################
101    Function Prototype Section
102 #########################################################
103**********************************************************/
104
105/************************************************
106************ SPECIAL FORMATTED COMMENT **********
107EW5 API FORMATTED COMMENT
108TYPE FUNCTION_PROTOTYPE
109
110LIBRARY  EWDB_API_LIB
111
112SUB_LIBRARY STRONG_MOTION_API
113
114LANGUAGE C
115
116LOCATION THIS_FILE
117
118FUNCTION ewdb_api_PutSMMessage
119
120SOURCE_LOCATION ewdb_api_PutSMMessage.c
121
122RETURN_TYPE int
123
124RETURN_VALUE EWDB_RETURN_SUCCESS
125RETURN_DESCRIPTION Success.
126
127RETURN_VALUE EWDB_RETURN_FAILURE
128RETURN_DESCRIPTION Failure.  See logfile for details.
129
130RETURN_VALUE EWDB_RETURN_WARNING
131RETURN_DESCRIPTION Warning.  The message was not inserted
132because the DB had no record of the channel or else the
133Lat/Lon of the component from which the channel came.  The
134channel check is done based on the SCNL from the message.
135See the logfile for the contents of the message, and for more
136info on why the message was not inserted.
137
138PARAMETER 1
139PARAM_NAME pMessage
140PARAM_TYPE SM_INFO *
141PARAM_DESCRIPTION  A pointer to a RW_STRONGMOTIONII message
142(in SM_INFO form), that the caller wishes to insert into the EW DBMS. 
143
144PARAMETER 2
145PARAM_NAME idEvent
146PARAM_TYPE EWDBid
147PARAM_DESCRIPTION DB Identifier of the event(that already exists
148in the DB)  that this strong motion message should be associated
149with.  The caller should set idEvent to 0 if they do not want
150this message associated with an Event. 
151
152DESCRIPTION This function stores a strong motion message in the
153DB and returns the idSMMessage of the new record.  If idEvent is
154a positive number, then the function will attempt to bind the new
155SMMessage to the Event identified by idEvent. 
156
157NOTE Be sure to properly initialize idEvent.  If a seemingly valid
158idEvent is passed, and no such Event exists, the function will fail,
159even though it can create the SMMessage without problems.
160If you do not have an idEvent, but have an author and an author's
161EventID, then you can use ewdb_api_CreateEvent() to get an idEvent
162from an author and author's EventID.
163
164*************************************************
165************************************************/
166int ewdb_api_PutSMMessage(SM_INFO * pMessage, EWDBid idEvent);
167
168
169/************************************************
170************ SPECIAL FORMATTED COMMENT **********
171EW5 API FORMATTED COMMENT
172TYPE FUNCTION_PROTOTYPE
173
174LIBRARY  EWDB_API_LIB
175
176SUB_LIBRARY STRONG_MOTION_API
177
178LANGUAGE C
179
180LOCATION THIS_FILE
181
182FUNCTION ewdb_api_DeleteSMMessage
183
184SOURCE_LOCATION ewdb_api_DeleteSMMessage.c
185
186RETURN_TYPE int
187
188RETURN_VALUE EWDB_RETURN_SUCCESS
189RETURN_DESCRIPTION Success.
190
191RETURN_VALUE EWDB_RETURN_FAILURE
192RETURN_DESCRIPTION Failure.  See logfile for details.
193
194PARAMETER 1
195PARAM_NAME idSMMessage
196PARAM_TYPE EWDBid
197PARAM_DESCRIPTION The DB id of the message that the caller
198wishes to delete.
199
200DESCRIPTION This function dissassociates a strong motion message
201with any Events, and then deletes the message.
202
203*************************************************
204************************************************/
205int ewdb_api_DeleteSMMessage(EWDBid idSMMessage);
206
207
208/************************************************
209************ SPECIAL FORMATTED COMMENT **********
210EW5 API FORMATTED COMMENT
211TYPE FUNCTION_PROTOTYPE
212
213LIBRARY  EWDB_API_LIB
214
215SUB_LIBRARY STRONG_MOTION_API
216
217LANGUAGE C
218
219LOCATION THIS_FILE
220
221FUNCTION ewdb_api_GetSMData
222
223SOURCE_LOCATION ewdb_api_GetSMData.c
224
225RETURN_TYPE int
226
227RETURN_VALUE EWDB_RETURN_SUCCESS
228RETURN_DESCRIPTION Success.
229
230RETURN_VALUE EWDB_RETURN_FAILURE
231RETURN_DESCRIPTION Failure.  See logfile for details.
232
233RETURN_VALUE EWDB_RETURN_WARNING
234RETURN_DESCRIPTION Partial Success.  The function successfully
235executed, but either 1)the caller's buffer wasn't large enough
236to retrieve all of the messages, and/or 2) there was a problem
237retrieving one or more of the messages.  If the value written
238to pNumRecordsFound at the completion of the function is greater
239than the iBufferRecLen parameter passed to the function, then
240more records were found than the caller's buffer could hold.
241If the value written to pNumRecordsRetrieved is less than
242the iBufferRecLen parameter passed to the function, then the
243function failed to retrieve atleast one of the messages that it found.
244
245PARAMETER 1
246PARAM_NAME pcsCriteria
247PARAM_TYPE EWDB_CriteriaStruct *
248PARAM_DESCRIPTION  The criteria struct for specifying criteria
249types and values for the query to retrieve messages. 
250pcsCriteria->Criteria, contains the flags which indicate
251which criteria to use in searching for messages.  NOTE: The
252Depth criteria is not supported by this function!  See
253EWDB_CriteriaStruct for more detail on criteria.
254
255PARAMETER 2
256PARAM_NAME szSta
257PARAM_TYPE char *
258PARAM_DESCRIPTION The Station name criteria for retrieving
259messages.  This param is only used for criteria if
260pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL
261flag.  '*' may be used as a wildcard.  This param must
262always be a valid pointer, the function may fail if it is set to NULL.
263
264PARAMETER 3
265PARAM_NAME szComp
266PARAM_TYPE char *
267PARAM_DESCRIPTION The Component name criteria for retrieving
268messages.  This param is only used for criteria if
269pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL
270flag.  '*' may be used as a wildcard.  This param must
271always be a valid pointer, the function may fail if it is set to NULL.
272
273PARAMETER 4
274PARAM_NAME szNet
275PARAM_TYPE char *
276PARAM_DESCRIPTION The Network name criteria for retrieving
277messages.  This param is only used for criteria if
278pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL
279flag.  '*' may be used as a wildcard.  This param must
280always be a valid pointer, the function may fail if it is set to NULL.
281
282PARAMETER 5
283PARAM_NAME szLoc
284PARAM_TYPE char *
285PARAM_DESCRIPTION The Location name criteria for retrieving
286messages.  This param is only used for criteria if
287pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL
288flag.  '*' may be used as a wildcard.  This param must
289always be a valid pointer, the function may fail if it is set to NULL.
290
291PARAMETER 6
292PARAM_NAME idEvent
293PARAM_TYPE EWDBid
294PARAM_DESCRIPTION The Event criteria for retrieving
295messages.  This param is only used for criteria if
296pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_IDEVENT
297flag.  This param must be set to a valid(existing) idEvent,
298if pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_IDEVENT
299flag, or the function will fail.
300
301PARAMETER 7
302PARAM_NAME iEventAssocFlag
303PARAM_TYPE int
304PARAM_DESCRIPTION  A flag indicating how the function should
305retrieve strong motion messages with respect to event association.
306If pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_IDEVENT flag,
307then this parameter is ignored;  otherwise, if this parameter is set
308to EWDB_SM_SEARCH_FOR_ALL_SMMESSAGES, then all messages meeting the
309criteria will be retrieved, otherwise if this param is set to
310EWDB_SM_SEARCH_FOR_ALL_UNASSOCIATED_MESSAGES, then only messages
311(meeting the criteria) that are NOT associated with an event, will
312be retrieved.
313
314PARAMETER 8
315PARAM_NAME pSMI
316PARAM_TYPE SM_INFO *
317PARAM_DESCRIPTION  A buffer allocated by the caller, where the
318function will place the retrieved messages. 
319
320PARAMETER 9
321PARAM_NAME BufferRecLen
322PARAM_TYPE int
323PARAM_DESCRIPTION  The length of the buffer(pBuffer) in terms of
324SM_INFO records.
325
326PARAMETER 10
327PARAM_NAME pNumRecordsFound
328PARAM_TYPE int *
329PARAM_DESCRIPTION  A pointer to an int where the function will
330write the number of messages found to meet the given criteria.
331NOTE:  The number found is not the number retrieved and written
332to the caller's buffer.  That is NumRecordsRetrieved.  If the
333number of messages found is greater than the caller's buffer will
334hold, then the function will return a warning.
335
336PARAMETER 11
337PARAM_NAME pNumRecordsRetrieved
338PARAM_TYPE int *
339PARAM_DESCRIPTION  A pointer to an int where the function will
340write the number of messages actualy retrieved by the function.
341This number will be less than or equal to the number found.
342
343DESCRIPTION This function retrieves strong motion messages
344from the DB that meet the criteria given by the caller. 
345
346*************************************************
347************************************************/
348int ewdb_api_GetSMData(EWDB_CriteriaStruct * pcsCriteria,
349                       char * szSta, char * szComp,
350                       char * szNet, char * szLoc,
351                       EWDBid idEvent, int iEventAssocFlag,
352                       SM_INFO * pSMI, int BufferRecLen,
353                       int * pNumRecordsFound, int * pNumRecordsRetrieved);
354
355
356/************************************************
357************ SPECIAL FORMATTED COMMENT **********
358EW5 API FORMATTED COMMENT
359TYPE FUNCTION_PROTOTYPE
360
361LIBRARY  EWDB_API_LIB
362
363SUB_LIBRARY STRONG_MOTION_API
364
365LANGUAGE C
366
367LOCATION THIS_FILE
368
369FUNCTION ewdb_api_GetSMDataWithChannelInfo
370
371SOURCE_LOCATION ewdb_api_GetSMDataWithChannelInfo.c
372
373RETURN_TYPE int
374
375RETURN_VALUE EWDB_RETURN_SUCCESS
376RETURN_DESCRIPTION Success.
377
378RETURN_VALUE EWDB_RETURN_FAILURE
379RETURN_DESCRIPTION Failure.  See logfile for details.
380
381RETURN_VALUE EWDB_RETURN_WARNING
382RETURN_DESCRIPTION Partial Success.  See ewdb_api_GetSMData().
383
384PARAMETER 1
385PARAM_NAME pcsCriteria
386PARAM_TYPE EWDB_CriteriaStruct *
387
388PARAMETER 2
389PARAM_NAME szSta
390PARAM_TYPE char *
391
392PARAMETER 3
393PARAM_NAME szComp
394PARAM_TYPE char *
395
396PARAMETER 4
397PARAM_NAME szNet
398PARAM_TYPE char *
399
400PARAMETER 5
401PARAM_NAME szLoc
402PARAM_TYPE char *
403
404PARAMETER 6
405PARAM_NAME idEvent
406PARAM_TYPE EWDBid
407
408PARAMETER 7
409PARAM_NAME iEventAssocFlag
410PARAM_TYPE int
411
412PARAMETER 8
413PARAM_NAME pSMCAS
414PARAM_TYPE EWDB_SMChanAllStruct *
415PARAM_DESCRIPTION  A buffer allocated by the caller, where the
416function will place the retrieved messages. 
417
418PARAMETER 9
419PARAM_NAME BufferRecLen
420PARAM_TYPE int
421
422PARAMETER 10
423PARAM_NAME pNumRecordsFound
424PARAM_TYPE int *
425
426PARAMETER 11
427PARAM_NAME pNumRecordsRetrieved
428PARAM_TYPE int *
429
430DESCRIPTION This function retrieves strong motion messages and
431associated info from the DB, for all messages that meet
432the criteria given by the caller.  This function retrieves the
433strong motion messages and Channel and Event association
434information for each message.
435
436NOTE This function is the same as ewdb_api_GetSMData(), except where
437noted above.  Please see ewdb_api_GetSMData() for better documentation
438on each of the parameters.
439
440*************************************************
441************************************************/
442int ewdb_api_GetSMDataWithChannelInfo(EWDB_CriteriaStruct * pcsCriteria,
443      char * szSta, char * szComp, char * szNet, char * szLoc,
444      EWDBid idEvent, int iEventAssocFlag, EWDB_SMChanAllStruct * pSMCAS, 
445      int BufferRecLen, int * pNumRecordsFound, int * pNumRecordsRetrieved);
446
447
448int ewdb_api_DeleteSMMessagesBeforeTime(int IN_tTime, int IN_bForce);
449
450#endif _EWDB_ORA_API_STRONG_MOTION_H
451
Note: See TracBrowser for help on using the repository browser.