Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members  

rw_strongmotionII.h

Go to the documentation of this file.
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 */

Generated on Tue May 6 09:16:08 2003 for Earthworm Libs by doxygen1.3-rc3