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 */