00001 /* 00002 * THIS FILE IS UNDER RCS - DO NOT MODIFY UNLESS YOU HAVE 00003 * CHECKED IT OUT USING THE COMMAND CHECKOUT. 00004 * 00005 * $Id: rw__strongmotionII_8h-source.html 2161 2006-05-19 16:55:03Z paulf $ 00006 * 00007 * Revision history: 00008 * $Log$ 00008 * Revision 1.1 2006/05/19 16:55:02 paulf 00008 * first inclusion 00008 * 00009 * Revision 1.3 2001/08/02 23:22:50 davidk 00010 * corrected a couple of comments. 00011 * 00012 * Revision 1.2 2001/04/06 17:22:52 davidk 00013 * Added formatted comments to the file. Added additional doucmentation. 00014 * 00015 * Revision 1.1 2001/04/06 17:16:06 davidk 00016 * Initial revision 00017 * 00018 * 00019 * 00020 */ 00021 00022 /************************************************ 00023 ************ SPECIAL FORMATTED COMMENT ********** 00024 EW API FORMATTED COMMENT 00025 TYPE LIBRARY 00026 00027 LIBRARY EW_LIBSRC 00028 00029 SUB_LIBRARY RW_STRONGMOTION_II 00030 00031 LOCATION THIS_FILE 00032 00033 DESCRIPTION Library for converting converting from an 00034 Earthworm TYPE_STRONGMOTION2 message to a structure and visa versa. 00035 <br><br> 00036 Each TYPE_STRONGMOTION2 message is intended to contain information for 00037 one channel only, with optional event association information. 00038 <br><br> 00039 Field units with multiple channels will produce multiple 00040 TYPE_STRONGMOTION2 messages. 00041 <br><br> 00042 Timestamps are in seconds since 1970/01/01 00:00:00.00 UTC. 00043 <br><br> 00044 Data are in units of cgs. (centimeters, grams, seconds) 00045 <br><br> 00046 <b>WARNING!</b> All measurements in the Earthworm TYPE_STRONGMOTION2 00047 message are assumed to be positive. SM_NULL indicates that 00048 a measurement is missing, and any other negative value 00049 will result in unpredictable behavior from strong motion 00050 applications. If you have sources that may produce signed 00051 values for PGA, PGV, PGD, or RSA values, you must be sure to 00052 change these to absolute values before they are passed to this 00053 library! 00054 <br> 00055 Written by Lynn Dietz, January 2001 00056 <br><br> 00057 00058 ************************************************* 00059 ************************************************/ 00060 00061 00062 /* rw_strongmotionII.h 00063 * 00064 * Header file for the functions in rw_strongmotionII.c that 00065 * convert from a TYPE_STRONGMOTION2 message to a structure 00066 * and visa versa. 00067 * 00068 * Each TYPE_STRONGMOTION2 message is intended to contain information 00069 * one channel only, with optional event association information. 00070 * Field units with multiple channels will produce multiple 00071 * TYPE_STRONGMOTION2 messages. 00072 * 00073 * Timestamps are in seconds since 1970/01/01 00:00:00.00 UTC. 00074 * 00075 * Data are in units of cgs. 00076 * 00077 * written by Lynn Dietz January 2001 00078 */ 00079 00080 #ifndef RW_STRONGMOTION_II_H 00081 #define RW_STRONGMOTION_II_H 00082 00083 #include <earthworm.h> 00084 /* 00085 #include <earthworm_defs.h> 00086 #include <earthworm_simple_funcs.h> 00087 */ 00088 00089 #include <trace_buf.h> 00090 00091 /* Useful constants 00092 *******************/ 00093 /************************************************ 00094 ************ SPECIAL FORMATTED COMMENT ********** 00095 EW5 API FORMATTED COMMENT 00096 TYPE DEFINE 00097 00098 LIBRARY EW_LIBSRC 00099 00100 SUB_LIBRARY RW_STRONGMOTION_II 00101 00102 LANGUAGE C 00103 00104 LOCATION THIS_FILE 00105 00106 CONSTANT_GROUP Scientific Constants 00107 00108 CONSTANT GRAVITY_CGS 00109 VALUE 978.03 00110 DESCRIPTION Gravity(g) in cm/sec/sec 00111 00112 ************************************************* 00113 ************************************************/ 00114 #define GRAVITY_CGS 978.03 /* Gravity in cm/sec/sec */ 00115 00116 /* Define maximum lengths for strings/arrays 00117 in and Earthworm TYPE_STRONGMOTION2 message 00118 *********************************************/ 00119 00120 /************************************************ 00121 ************ SPECIAL FORMATTED COMMENT ********** 00122 EW5 API FORMATTED COMMENT 00123 TYPE DEFINE 00124 00125 LIBRARY EW_LIBSRC 00126 00127 SUB_LIBRARY RW_STRONGMOTION_II 00128 00129 LANGUAGE C 00130 00131 LOCATION THIS_FILE 00132 00133 CONSTANT_GROUP Strong Motion Message Constants 00134 00135 CONSTANT SM_MAX_RSA 00136 VALUE 20 00137 DESCRIPTION Maximum number of spectral values for 00138 a given message. 00139 00140 CONSTANT SM_NULL 00141 VALUE -1 00142 DESCRIPTION NULL value for PGA, PGV, and PGD measurments. 00143 If any of the peak measurments for a message are not 00144 available, use SM_NULL in there place to indicate so. 00145 All measurements in the Earthworm TYPE_STRONGMOTION2 00146 message are assumed to be positive. SM_NULL indicates that 00147 a measurement is missing, and any other negative value 00148 will result in unpredictable behavior from strong motion 00149 applications. 00150 00151 ************************************************* 00152 ************************************************/ 00153 #define SM_MAX_RSA 20 /* max # spectral values for a given channel */ 00154 #define SM_NULL -1 /* null value for period & RSA */ 00155 00156 00157 /************************************************ 00158 ************ SPECIAL FORMATTED COMMENT ********** 00159 EW5 API FORMATTED COMMENT 00160 TYPE DEFINE 00161 00162 LIBRARY EW_LIBSRC 00163 00164 SUB_LIBRARY RW_STRONGMOTION_II 00165 00166 LANGUAGE C 00167 00168 LOCATION THIS_FILE 00169 00170 CONSTANT_GROUP Strong Motion Alternate Time Codes 00171 00172 CONSTANT SM_ALTCODE_NONE 00173 VALUE 0 00174 DESCRIPTION Code for no alternate time. 00175 00176 CONSTANT SM_ALTCODE_RECEIVING_MODULE 00177 VALUE 1 00178 DESCRIPTION Code for an alternate time derived by 00179 a program module that receives a message from a 00180 box in the field. 00181 00182 CONSTANT SM_ALTCODE_DATABASE 00183 VALUE 2 00184 DESCRIPTION Code for an alternate time derived by 00185 the database or strong motion database insertion module. 00186 00187 CONSTANT SM_ALTCODE_AUTOMATED_REVIEWER 00188 VALUE 3 00189 DESCRIPTION Code for an alternate time derived by 00190 a Human (who has hopefully reviewed the data). 00191 00192 ************************************************* 00193 ************************************************/ 00194 /* Sources for the alternate time in the SM_DATA structure 00195 *********************************************************/ 00196 #define SM_ALTCODE_NONE 0 00197 #define SM_ALTCODE_RECEIVING_MODULE 1 00198 #define SM_ALTCODE_DATABASE 2 00199 #define SM_ALTCODE_AUTOMATED_REVIEWER 3 00200 #define SM_ALTCODE_HUMAN_REVIEWER 4 00201 00202 00203 /************************************************ 00204 ************ SPECIAL FORMATTED COMMENT ********** 00205 EW5 API FORMATTED COMMENT 00206 TYPE TYPEDEF 00207 00208 LIBRARY EW_LIBSRC 00209 00210 SUB_LIBRARY RW_STRONGMOTION_II 00211 00212 LANGUAGE C 00213 00214 LOCATION THIS_FILE 00215 00216 TYPEDEF SM_INFO 00217 TYPE_DEFINITION struct _SM_INFO 00218 DESCRIPTION Structure that contains data for a 00219 single strong motion message. This structure 00220 is equivalent to the binary form of a strong 00221 motion message(without a MSG_LOGO). 00222 00223 MEMBER sta 00224 MEMBER_TYPE char[TRACE_STA_LEN] 00225 MEMBER_DESCRIPTION NTS, Site code as per IRIS SEED. 00226 00227 MEMBER comp 00228 MEMBER_TYPE char[TRACE_CHAN_LEN] 00229 MEMBER_DESCRIPTION NTS, Component code as per IRIS SEED. 00230 00231 MEMBER net 00232 MEMBER_TYPE char[TRACE_NET_LEN] 00233 MEMBER_DESCRIPTION NTS, Network code as per IRIS SEED. 00234 00235 MEMBER loc 00236 MEMBER_TYPE char[TRACE_LOC_LEN] 00237 MEMBER_DESCRIPTION NTS, Location code as per IRIS SEED. 00238 00239 MEMBER qid 00240 MEMBER_TYPE char[EVENTID_SIZE] 00241 MEMBER_DESCRIPTION EventId that the message is associated 00242 with. This EventID is the one specified by qAuthor. 00243 00244 MEMBER qauthor 00245 MEMBER_TYPE char[AUTHOR_FIELD_SIZE] 00246 MEMBER_DESCRIPTION Author of an event with which this 00247 message is associated. The author assigns the qid. 00248 00249 MEMBER t 00250 MEMBER_TYPE double 00251 MEMBER_DESCRIPTION The main timestamp for the message. If the 00252 message came from an SM box in the field, then this is the trigger 00253 time reported by the box. If the message came from a module processing 00254 continuous telemetry, then this is the pick time or earlies of PGA, PGV, 00255 or PGD time. (seconds since 1970/01/01 00:00:00.00) 00256 00257 MEMBER talt 00258 MEMBER_TYPE double 00259 MEMBER_DESCRIPTION (Optional) Alternate timestamp for the message. 00260 This param is provided as a sanity check or correction of the 00261 main timestamp(t). This timestamp could be assigned by an acquisition 00262 module, database loader, human, or other. The author type of this 00263 timestamp is determined by altcode(see below). 00264 (seconds since 1970/01/01 00:00:00.00) 00265 00266 MEMBER altcode 00267 MEMBER_TYPE int 00268 MEMBER_DESCRIPTION (Required if talt is specified.) 00269 Code specifying the source of the alternate time field(talt). 00270 See SM_ALTCODE_NONE for a list of recognized source codes. 00271 00272 MEMBER pga 00273 MEMBER_TYPE double 00274 MEMBER_DESCRIPTION The Peak Ground Acceleration(PGA) for this 00275 message. (cm/s/s) 00276 00277 MEMBER tpga 00278 MEMBER_TYPE double 00279 MEMBER_DESCRIPTION Time of the pga. (seconds since 1970) 00280 00281 MEMBER pgv 00282 MEMBER_TYPE double 00283 MEMBER_DESCRIPTION The Peak Ground Velocity(PGV) for this 00284 message. (cm/s) 00285 00286 MEMBER tpgv 00287 MEMBER_TYPE double 00288 MEMBER_DESCRIPTION Time of the pgv. (seconds since 1970) 00289 00290 MEMBER pgd 00291 MEMBER_TYPE double 00292 MEMBER_DESCRIPTION The Peak Ground Displacement(PGD) for this 00293 message. (cm) 00294 00295 MEMBER tpgd 00296 MEMBER_TYPE double 00297 MEMBER_DESCRIPTION Time of the pgd. (seconds since 1970) 00298 00299 MEMBER nrsa 00300 MEMBER_TYPE int 00301 MEMBER_DESCRIPTION Number of response spectrum accel(RSA) pairs. 00302 Valid value range is (0 - SM_MAX_RSA). 00303 00304 MEMBER pdrsa 00305 MEMBER_TYPE double[SM_MAX_RSA] 00306 MEMBER_DESCRIPTION Period(s) at which RSA values are given. 00307 00308 MEMBER rsa 00309 MEMBER_TYPE double[SM_MAX_RSA] 00310 MEMBER_DESCRIPTION RSA value for each given period. (cm/s/s) 00311 00312 MEMBER tload 00313 MEMBER_TYPE double 00314 MEMBER_DESCRIPTION Time the message was first loaded into an 00315 Earthworm DB. (seconds since 1970) NOTE: This field is 00316 not part of ascii TYPE_STRONGMOTIONII msg, but may be filled 00317 when pulling data from DBMS. 00318 00319 NOTE NTS when used above refers to (NULL Terminated String). 00320 00321 ************************************************* 00322 ************************************************/ 00323 /* Structure to contain strongmotion data from one channel 00324 In the comments below, NTS = Null Terminated String 00325 *********************************************************/ 00326 typedef struct _SM_INFO { 00327 00328 /* fields supplied in TYPE_STRONGMOTION2 msg */ 00329 char sta[TRACE_STA_LEN]; /* REQUIRED: NTS, Site code as per IRIS SEED */ 00330 char comp[TRACE_CHAN_LEN]; /* REQUIRED: NTS, Component code as per IRIS SEED */ 00331 char net[TRACE_NET_LEN]; /* REQUIRED: NTS, Network code as per IRIS SEED */ 00332 char loc[TRACE_LOC_LEN]; /* OPTIONAL: NTS, Location code as per IRIS SEED */ 00333 char qid[EVENTID_SIZE]; /* OPTIONAL: NTS, eventid data associates with */ 00334 char qauthor[AUTHOR_FIELD_SIZE]; /* OPTIONAL: NTS, author of the eventid */ 00335 /* (required if qid is given) */ 00336 double t; /* REQUIRED: time: trigger reported by SM box, */ 00337 /* or pick time from continuous telemetry, */ 00338 /* or earliest of tpga, tpgv, tpgd */ 00339 /* (seconds since 1970/01/01 00:00:00.00) */ 00340 double talt; /* OPTIONAL: alternate time, reported by */ 00341 /* nobody, acq. software, analyst, etc. */ 00342 int altcode; /* OPTIONAL: code specifying the source of */ 00343 /* the alternate time field */ 00344 double pga; /* REQUIRED: peak ground acceleration (cm/s/s) */ 00345 double tpga; /* OPTIONAL: time of pga */ 00346 double pgv; /* REQUIRED: peak ground velocity (cm/s) */ 00347 double tpgv; /* OPTIONAL: time of pgv */ 00348 double pgd; /* REQUIRED: peak ground displacement (cm) */ 00349 double tpgd; /* OPTIONAL: time of pgd */ 00350 int nrsa; /* REQUIRED: # response spectrum accel (RSA) pairs*/ 00351 /* Valid range for nrsa is 0 to SM_MAX_RSA */ 00352 double pdrsa[SM_MAX_RSA]; /* period (s) at which RSA values are given */ 00353 double rsa[SM_MAX_RSA]; /* RSA value (cm/s/s) at given period */ 00354 00355 /* fields supplied by DBMS: */ 00356 double tload; /* time data was loaded into DBMS - this field is */ 00357 /* not part of ascii TYPE_STRONGMOTIONII msg, */ 00358 /* but may be filled when pulling data from DBMS*/ 00359 } SM_INFO; 00360 00361 00362 00363 /* Function Prototypes 00364 *********************/ 00365 00366 /************************************************ 00367 ************ SPECIAL FORMATTED COMMENT ********** 00368 EW5 API FORMATTED COMMENT 00369 TYPE FUNCTION_PROTOTYPE 00370 00371 LIBRARY EW_LIBSRC 00372 00373 SUB_LIBRARY RW_STRONGMOTION_II 00374 00375 LANGUAGE C 00376 00377 LOCATION THIS_FILE 00378 00379 FUNCTION rd_strongmotionII 00380 00381 SOURCE_LOCATION src/libsrc/util/rw_strongmotionII.c 00382 00383 RETURN_TYPE int 00384 00385 RETURN_VALUE 0 00386 RETURN_DESCRIPTION Success. 00387 00388 RETURN_VALUE -1 00389 RETURN_DESCRIPTION Failure. See logfile for details. 00390 00391 00392 PARAMETER 1 00393 PARAM_NAME msg 00394 PARAM_TYPE char * 00395 PARAM_DESCRIPTION The strong motion message. The first line 00396 of the message should be the SCNL line. 00397 00398 PARAMETER 2 00399 PARAM_NAME msglen 00400 PARAM_TYPE int 00401 PARAM_DESCRIPTION The length of the msg in bytes. 00402 00403 PARAMETER 3 00404 PARAM_NAME sm 00405 PARAM_TYPE SM_INFO * 00406 PARAM_DESCRIPTION A pointer to an SM_INFO struct allocated 00407 by the caller, where the function will result the SM_INFO 00408 struct derived from the message. 00409 00410 00411 DESCRIPTION This function reads an ascii TYPE_STRONGMOTION2 00412 message and fills in a SM_INFO structure. It returns 0 on success, 00413 -1 on failure. 00414 00415 NOTE Example of a TYPE_STRONGMOTION2 message. 00416 <br><br><font size=-1 face=monospace> 00417 SCNL: CMB.BHZ.BK. <br> 00418 TIME: 2001/02/25 02:37:00.000 <br> 00419 ALT: 2001/02/25 02:40:40.000 CODE: 1 <br> 00420 PGA: 6.846210 TPGA: 2001/02/25 02:37:00.000 <br> 00421 PGV: 0.140000 TPGV: 2001/02/25 02:37:00.000 <br> 00422 PGD: 0.000000 TPGD: 2001/02/25 02:37:00.000 <br> 00423 RSA: 3/0.30 4.415404/1.00 0.925639/3.00 0.297907 <br> 00424 QID: 41059467 014024003:UCB <br> 00425 </b></font> 00426 00427 ************************************************* 00428 ************************************************/ 00429 int rd_strongmotionII( char *msg, int msglen, SM_INFO *sm ); 00430 00431 /************************************************ 00432 ************ SPECIAL FORMATTED COMMENT ********** 00433 EW5 API FORMATTED COMMENT 00434 TYPE FUNCTION_PROTOTYPE 00435 00436 LIBRARY EW_LIBSRC 00437 00438 SUB_LIBRARY RW_STRONGMOTION_II 00439 00440 LANGUAGE C 00441 00442 LOCATION THIS_FILE 00443 00444 FUNCTION wr_strongmotionII 00445 00446 SOURCE_LOCATION src/libsrc/util/rw_strongmotionII.c 00447 00448 RETURN_TYPE int 00449 00450 RETURN_VALUE 0 00451 RETURN_DESCRIPTION Success. 00452 00453 RETURN_VALUE -1 00454 RETURN_DESCRIPTION Failure. This is caused by a 00455 buffer overflow, where the caller's buffer was too 00456 small to hold the entire message generated by the 00457 function. If the caller believes their buffer should 00458 be adequately large, then one or more of the strings 00459 in the SM_INFO struct may not be properly terminated. 00460 00461 00462 PARAMETER 1 00463 PARAM_NAME sm 00464 PARAM_TYPE SM_INFO * 00465 PARAM_DESCRIPTION Pointer to an SM_INFO struct that the 00466 function will read to get the information for the 00467 TYPE_STRONGMOTION2 message. 00468 00469 PARAMETER 2 00470 PARAM_NAME buf 00471 PARAM_TYPE char * 00472 PARAM_DESCRIPTION Pointer to a buffer allocated by the caller 00473 where the function will write the TYPE_STRONGMOTION2 message. 00474 00475 PARAMETER 3 00476 PARAM_NAME buflen 00477 PARAM_TYPE int 00478 PARAM_DESCRIPTION The length of the caller's buffer(buf) in bytes. 00479 00480 00481 DESCRIPTION Reads a SM_INFO structure and writes an ascii 00482 TYPE_STRONGMOTION2 message (null terminated). It returns 00483 0 on success, and -1 on failure. See rd_strongmotion for 00484 an example of a TYPE_STRONGMOTION2 message. 00485 00486 ************************************************* 00487 ************************************************/ 00488 int wr_strongmotionII( SM_INFO *sm, char *buf, int buflen ); 00489 00490 /************************************************ 00491 ************ SPECIAL FORMATTED COMMENT ********** 00492 EW5 API FORMATTED COMMENT 00493 TYPE FUNCTION_PROTOTYPE 00494 00495 LIBRARY EW_LIBSRC 00496 00497 SUB_LIBRARY RW_STRONGMOTION_II 00498 00499 LANGUAGE C 00500 00501 LOCATION THIS_FILE 00502 00503 FUNCTION log_strongmotionII 00504 00505 SOURCE_LOCATION src/libsrc/util/rw_strongmotionII.c 00506 00507 RETURN_TYPE void 00508 00509 PARAMETER 1 00510 PARAM_NAME sm 00511 PARAM_TYPE SM_INFO * 00512 PARAM_DESCRIPTION Pointer to an SM_INFO struct whose 00513 contents the function will log to a file. 00514 00515 00516 DESCRIPTION Writes the contents of a SM_INFO structure 00517 to an Earthworm log file. 00518 00519 ************************************************* 00520 ************************************************/ 00521 void log_strongmotionII( SM_INFO *sm ); 00522 00523 #endif /* #ifndef RW_STRONGMOTION_II_H */