ewdb_internal_CreateSMMessage()

Prototype: |
int ewdb_internal_CreateSMMessage( | EWDBid * pidSMMessage, double tMain, double tLoad, double tAlt, int iAltCode, double tPGA, double tPGV, double tPGD, EWDBid idChan, EWDBid idEvent);
Source File: | ewdb_internal_CreateSMMessage.c
Description: | This function Creates an SMMessage record in the DB and returns the idSMMessage of the new record. It does not create all the strong motion measurements that are part of the message. The caller must call ewdb_internal_CreateSMMotion() for each motion measurment in the message. If idEvent is a positive number, then the function will attempt to bind the new SMMessage to the Event identified by idEvent.
Note: | Be sure to properly initialize idEvent. If a seemingly valid idEvent is passed, and no such Event exists, the function will fail, even though it can create the SMMessage itself without problems. If you do not have an idEvent, but have an author and an author's EventID, then you can use ewdb_api_CreateEvent() to get an idEvent from an author and author's EventID.
RETURN CODE INFO
Return Type: | int
Return Value | Description
EWDB_RETURN_SUCCESS | Success.
EWDB_RETURN_FAILURE | Failure. See logfile for details.
PARAMETER INFO
Parameter | Type | Description
pidSMMessage | EWDBid * | A pointer to an EWDBid where the function will write the idSMMessage of the newly created message. The idSMMessage will only be written if the function returns EWDB_RETURN_SUCCESS.
tMain | double | This is the main timestamp for the message. This is the one given by the program/device that recorded/declared the motion. (seconds since 1970)
tLoad | double | This is the time that the message was first loaded into a Database. (This is kind of a sanity timestamp). This timestamp should only be assigned once, when the message is first loaded into a DB. (seconds since 1970)
tAlt | double | This is an alternate time to tMain. It can be assigned by different entities. iAltCode describes how the time was derived. (seconds since 1970)
iAltCode | int | A code that describes how tAlt was derived. See SM_ALTCODE_NONE in rw_strongmotion.h for more information.
tPGA | double | (OPTIONAL) Time of the Peak Ground Acceleration(PGA) for this motion. (seconds since 1970)
tPGV | double | (OPTIONAL) Time of the Peak Ground Velocity(PGV) for this motion. (seconds since 1970)
tPGD | double | (OPTIONAL) Time of the Peak Ground Displacement(PGD) for this motion. (seconds since 1970)
idChan | EWDBid | DB Identifier of the channel that recorded this strong motion message.
idEvent | EWDBid | DB Identifier of the event(that already exists in the DB) that this strong motion message should be associated with. The caller should set idEvent to 0 if they do not want this message associated with an Event.
Group: | EWDB_API_LIB
Sub Group: | STRONG_MOTION-INTERNAL
Language: | C
Location: | ./src/oracle/schema-working/src/include/internal/ewdb_sm_internal.h

ewdb_internal_CreateSMMotion()

Prototype: |
int ewdb_internal_CreateSMMotion( | EWDBid * pidSMMotion, EWDBid idSMMessage, int iMotionType, double dPeriod, double dMeasurement);
Source File: | ewdb_internal_CreateSMMotion.c
Description: | This function Creates an SMMotion record in the DB and returns the idSMMotion of the new record.
RETURN CODE INFO
Return Type: | int
Return Value | Description
EWDB_RETURN_SUCCESS | Success.
EWDB_RETURN_FAILURE | Failure. See logfile for details.
PARAMETER INFO
Parameter | Type | Description
pidSMMotion | EWDBid * | A pointer to an EWDBid where the function will write the idSMMotion of the newly created motion measurment.
idSMMessage | EWDBid | The DB id of the message that this motion measurment is a part of.
iMotionType | int | The type of motion. This must be either EWDB_SM_MOTION_TYPE_ACCELERATION, EWDB_SM_MOTION_TYPE_VELOCITY, or EWDB_SM_MOTION_TYPE_DISPLACEMENT.
dPeriod | double | For spectral response measurements, this is the time period associated with the motion. For other types of measurments, this is a special code (see EWDB_SM_PERIOD_PEAK_VALUE_CODE) indicating a special measurement type.
dMeasurement | double | The measurement of the motion. This value is in terms of centimeters and seconds, so should be either cm/s/s for acceleration, cm/s for velocity, or cm for displacement.
Group: | EWDB_API_LIB
Sub Group: | STRONG_MOTION-INTERNAL
Language: | C
Location: | ./src/oracle/schema-working/src/include/internal/ewdb_sm_internal.h

ewdb_internal_GetAllSMMessages()

Prototype: |
int ewdb_internal_GetAllSMMessages( | char * IN_szSta, char * IN_szComp, char * IN_szNet, char * IN_szLoc, EWDBid IN_idEvent, int IN_iQueryType, EWDB_CriteriaStruct * IN_pCriteria, void * pBuffer, int iBufferRecLen, int * pNumRecordsFound, int * pNumRecordsRetrieved);
Source File: | ewdb_internal_GetAllSMMessages.c
Description: | This function is the big, bad, nasty, smelly, 4000Lb gorilla of strong motion data retrieval. It is a multiplexed work of some nefarious creature. Based on the parameters passed in, it executes one of mutiple(Currently 5) genres of queries to retrieve strong motion messages, and then retrieves the data into one of multiple(currently 2) buffer types. This function exists because it was deemed better to write one large hairy function than to write ten simpler functions that had lots of redundant code between them. The caller passes in a set of criteria and a type of query to execute, and then the function executes the query and retrieves the data into the caller's buffer, in a record format determined by the query type.
Note: | This function retrieves only the messages and (optionally) non-motion associated info, such as Channel and Event association. It does not retrieve the actual motion measurements. This must be done by calling ewdb_internal_GetSMMotionsForMessage() after calling this function.
RETURN CODE INFO
Return Type: | int
Return Value | Description
EWDB_RETURN_SUCCESS | Success.
EWDB_RETURN_FAILURE | Failure. See logfile for details.
EWDB_RETURN_WARNING | Partial Success. The function successfully executed, but either 1)the caller's buffer wasn't large enough to retrieve all of the messages, and/or 2) there was a problem retrieving one or more of the messages. If the value written to pNumRecordsFound at the completion of the function is greater than the iBufferRecLen parameter passed to the function, then more records were found than the caller's buffer could hold. If the value written to pNumRecordsRetrieved is less than the iBufferRecLen parameter passed to the function, then the function failed to retrieve atleast one of the messages that it found.
PARAMETER INFO
Parameter | Type | Description
IN_szSta | char * | The Station name criteria for retrieving messages. This param is only used for criteria if IN_pCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
IN_szComp | char * | The Component name criteria for retrieving messages. This param is only used for criteria if IN_pCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
IN_szNet | char * | The Network name criteria for retrieving messages. This param is only used for criteria if IN_pCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
IN_szLoc | char * | The Location name criteria for retrieving messages. This param is only used for criteria if IN_pCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
IN_idEvent | EWDBid | The Event criteria for retrieving messages. This param is only used for criteria if IN_pCriteria->Criteria includes the EWDB_CRITERIA_USE_IDEVENT flag. This param must be set to a valid(existing) idEvent, if IN_pCriteria->Criteria includes the EWDB_CRITERIA_USE_IDEVENT flag, or the function will fail.
IN_iQueryType | int | The type of search query to use to retrieve messages and related info. See EWDB_SM_SELECT_SMMESSAGES_W_INFO and related constants for more details.
IN_pCriteria | EWDB_CriteriaStruct * | The criteria struct for specifying criteria types and values for the query to retrieve messages. IN_pCriteria->Criteria, contains the flags which indicate which criteria to use in searching for messages. NOTE: The Depth criteria is not supported by this function! See EWDB_CriteriaStruct for more detail on criteria.
pBuffer | void * | A buffer allocated by the caller, where the function will place the retrieved messages. See the description of iBufferRecLen immediately below, for more information on buffer records.
iBufferRecLen | int | The length of the buffer(pBuffer) in terms of records. This function supports multiple record types for the retrieval buffer, dependent upon the iQueryType parameter. If iQueryType is (EWDB_SM_SELECT_SMMESSAGES_W_INFO, EWDB_SM_SELECT_SMMESSAGES_W_CHANNEL_INFO, EWDB_SM_SELECT_SMMESSAGES_W_CHANNEL_INFO_BY_EVENT, or EWDB_SM_SELECT_SMMESSAGES_W_CHANNEL_INFO_WITHOUT_EVENT) then the buffer records are expected to be of type EWDB_SMChanAllStruct. If iQueryType is EWDB_SM_SELECT_SMMESSAGES_W_ID_ONLY, then the buffer records are expected to be of type EWDBid.
pNumRecordsFound | int * | A pointer to an int where the function will write the number of messages found to meet the given criteria. NOTE: The number found is not the number retrieved and written to the caller's buffer. That is NumRecordsRetrieved. If the number of messages found is greater than the caller's buffer will hold, then the function will return a warning.
pNumRecordsRetrieved | int * | A pointer to an int where the function will write the number of messages actualy retrieved by the function. This number will be less than or equal to the number found.
Group: | EWDB_API_LIB
Sub Group: | STRONG_MOTION-INTERNAL
Language: | C
Location: | ./src/oracle/schema-working/src/include/internal/ewdb_sm_internal.h

ewdb_internal_GetSMMessages()

Prototype: |
int ewdb_internal_GetSMMessages( | EWDB_CriteriaStruct * pcsCriteria, char * szSta, char * szComp, char * szNet, char * szLoc, EWDBid idEvent, int iQueryType, char * szStructType, void * pBuffer, int iBufferRecLen, int * pNumRecordsFound, int * pNumRecordsRetrieved);
Source File: | ewdb_internal_GetSMMessages.c
Description: | This function retrieves strong motion messages and associated info for all messages that meet the criteria given by the caller. This function retrieves the strong motion messages(SMMessages) complete with all of the motion measurements for each message, and Channel and Event association information for each message if the caller's buffer will accomodate it.
RETURN CODE INFO
Return Type: | int
Return Value | Description
EWDB_RETURN_SUCCESS | Success.
EWDB_RETURN_FAILURE | Failure. See logfile for details.
EWDB_RETURN_WARNING | Partial Success. The function successfully executed, but either 1)the caller's buffer wasn't large enough to retrieve all of the messages, and/or 2) there was a problem retrieving one or more of the messages. If the value written to pNumRecordsFound at the completion of the function is greater than the iBufferRecLen parameter passed to the function, then more records were found than the caller's buffer could hold. If the value written to pNumRecordsRetrieved is less than the iBufferRecLen parameter passed to the function, then the function failed to retrieve atleast one of the messages that it found.
PARAMETER INFO
Parameter | Type | Description
pcsCriteria | EWDB_CriteriaStruct * | The criteria struct for specifying criteria types and values for the query to retrieve messages. pcsCriteria->Criteria, contains the flags which indicate which criteria to use in searching for messages. NOTE: The Depth criteria is not supported by this function! See EWDB_CriteriaStruct for more detail on criteria.
szSta | char * | The Station name criteria for retrieving messages. This param is only used for criteria if pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
szComp | char * | The Component name criteria for retrieving messages. This param is only used for criteria if pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
szNet | char * | The Network name criteria for retrieving messages. This param is only used for criteria if pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
szLoc | char * | The Location name criteria for retrieving messages. This param is only used for criteria if pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_SCNL flag. '*' may be used as a wildcard. This param must always be a valid pointer, the function may fail if it is set to NULL.
idEvent | EWDBid | The Event criteria for retrieving messages. This param is only used for criteria if pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_IDEVENT flag. This param must be set to a valid(existing) idEvent, if pcsCriteria->Criteria includes the EWDB_CRITERIA_USE_IDEVENT flag, or the function will fail.
iQueryType | int | The type of search query to use to retrieve messages and related info. See EWDB_SM_SELECT_SMMESSAGES_W_INFO and related constants for more details.
szStructType | char * | A string representation of the structure type of the caller's buffer. (The format the caller is expecting to retrieve data in.) Currently only "SM_INFO" and "EWDB_SMChanAllStruct" are supported, any other structure type will cause the function to fail.
pBuffer | void * | A buffer allocated by the caller, where the function will place the retrieved messages. See the description of iBufferRecLen immediately below, for more information on buffer records.
iBufferRecLen | int | The length of the buffer(pBuffer) in terms of records. The record type is given by the szStructType param. See szStructType(above) for a description of what structure types are supported.
pNumRecordsFound | int * | A pointer to an int where the function will write the number of messages found to meet the given criteria. NOTE: The number found is not the number retrieved and written to the caller's buffer. That is NumRecordsRetrieved. If the number of messages found is greater than the caller's buffer will hold, then the function will return a warning.
pNumRecordsRetrieved | int * | A pointer to an int where the function will write the number of messages actualy retrieved by the function. This number will be less than or equal to the number found.
Group: | EWDB_API_LIB
Sub Group: | STRONG_MOTION-INTERNAL
Language: | C
Location: | ./src/oracle/schema-working/src/include/internal/ewdb_sm_internal.h

ewdb_internal_GetSMMotionsForMessage()

Prototype: |
int ewdb_internal_GetSMMotionsForMessage( | EWDBid idSMMessage, EWDB_SMMotionStruct * pBuffer, int iBufferRecLen, int * pNumRecordsFound, int * pNumRecordsRetrieved);
Source File: | ewdb_internal_GetSMMotionsForMessage.c
Description: | This function retrieves all strong motion measurements for a given strong motion message(SMMessage). It writes the results as an array of EWDB_SMMotionStruct.
RETURN CODE INFO
Return Type: | int
Return Value | Description
EWDB_RETURN_SUCCESS | Success.
EWDB_RETURN_FAILURE | Failure. See logfile for details.
EWDB_RETURN_WARNING | Partial Success. The function successfully executed, but the caller's buffer wasn't large enough to retrieve all of the messages. See *pNumRecordsFound for the neccessary buffersize to retrieve all selected motion measurments.
PARAMETER INFO
Parameter | Type | Description
idSMMessage | EWDBid | The DB ID of the strong motion message for which the caller wants to retrieve motion measurments.
pBuffer | EWDB_SMMotionStruct * | Buffer allocated by the caller, where the function will write the retrieved motion measurements for the given SMMessage.
iBufferRecLen | int | The length of the caller's buffer(pBuffer) in terms of EWDB_SMMotionStruct records.
pNumRecordsFound | int * | A pointer to an int where the function will write the number of motions found. NOTE: The number found is not the number retrieved and written to the caller's buffer. That is NumRecordsRetrieved. If the number of messages found is greater than the caller's buffer will hold, then the function will return a warning.
pNumRecordsRetrieved | int * | A pointer to an int where the function will write the number of motion measurements actualy retrieved by the function. This will be less than or equal to the number found.
Group: | EWDB_API_LIB
Sub Group: | STRONG_MOTION-INTERNAL
Language: | C
Location: | ./src/oracle/schema-working/src/include/internal/ewdb_sm_internal.h