Adding Location Code to Earthworm Messages
2004/03/05:LDD, updated 2005/03/18:LDD
________________________________________________________________________________

SUMMARY

Earthworm msg types used by NCSN that will require new versions
to implement Location code in SCNL:

Current Msg Type     New Msg Type            Generated by
----------------     -------------           ------------
TYPE_TRACEBUF        TYPE_TRACEBUF2          all data sources

TYPE_TRACE_COMP_UA   TYPE_TRACE2_COMP_UA     compress_UA

TYPE_PICK2K          TYPE_PICK_SCNL          pick_ew

TYPE_CODA2K          TYPE_CODA_SCNL          pick_ew

TYPE_EVENT2K         TYPE_EVENT_SCNL         eqproc,eqprelim

TYPE_CARLSTATRIG     TYPE_CARLSTATRIG_SCNL   carlstatrig

TYPE_TRIGLIST2K      TYPE_TRIGLIST_SCNL      carlsubtrig,arc2trignc,
                                             evansassoc

TYPE_LPTRIG          TYPE_LPTRIG_SCNL        evanstrig

Format already contains fields for L, but code must be changed
to implement it:
TYPE_HYP2000ARC      TYPE_HYP2000ARC         eqcoda,hyp2000_mgr

________________________________________________________________________________


Adding Location code to Trace Data Messages
-------------------------------------------

TYPE_TRACEBUF2 & TYPE_TRACE2_COMP_UA

The new trace data message header will be of the same length as 
the current message header. The location and version fields will 
be carved out of the currently over-sized chan field.  All other
fields will remain the same length and in the same position in 
the header. This means that the station and network fields will
still remain over-sized with respect to the SEED field length
requirements.

Here's the original and the new trace header, from trace_buf.h:

/*---------------------------------------------------------------------------*
 * Definition of original TYPE_TRACEBUF header with CSS3.0-length SNC fields *
 *                                                                           *
 * NOTE: The principal time fields in the TRACE_HEADER are:                  * 
 *         starttime, nsamp, and samprate.                                   *
 *       The endtime field is included as a redundant convenience.           *
 *---------------------------------------------------------------------------*/

#define NETWORK_NULL_STRING "-"

#define	TRACE_STA_LEN	7
#define	TRACE_CHAN_LEN	9
#define	TRACE_NET_LEN	9
#define TRACE_LOC_LEN   3

typedef struct {
        int     pinno;                 /* Pin number */
        int     nsamp;                 /* Number of samples in packet */
        double  starttime;             /* time of first sample in epoch seconds
                                          (seconds since midnight 1/1/1970) */
        double  endtime;               /* Time of last sample in epoch seconds */
        double  samprate;              /* Sample rate; nominal */
        char    sta[TRACE_STA_LEN];    /* Site name */
        char    net[TRACE_NET_LEN];    /* Network name */
        char    chan[TRACE_CHAN_LEN];  /* Component/channel code */
        char    datatype[3];           /* Data format code */
        char    quality[2];            /* Data-quality field */
        char    pad[2];                /* padding */
} TRACE_HEADER;

/*---------------------------------------------------------------------------*
 * Definition of TYPE_TRACEBUF2 header with SEED SNCL fields.                *
 *                                                                           *
 * The new TRACE2_HEADER is the same length as the original TRACE_HEADER.    *
 *  + sta and net fields remain unchanged (longer than required by SEED).    *
 *  + chan field is shortened to appropriate SEED length.                    *
 *  + loc and version fields were added in the extra chan field bytes.       *      
 *  + all other fields remain unchanged (same length, same position).        *
 *                                                                           *
 * NOTE: The principal time fields in the TRACE_HEADER are:                  * 
 *         starttime, nsamp, and samprate.                                   *
 *       The endtime field is included as a redundant convenience.           *
 *---------------------------------------------------------------------------*/

#define	TRACE2_STA_LEN	  7    /* SEED: 5 chars plus terminating NULL */
#define	TRACE2_NET_LEN	  9    /* SEED: 2 chars plus terminating NULL */
#define	TRACE2_CHAN_LEN   4    /* SEED: 3 chars plus terminating NULL */
#define	TRACE2_LOC_LEN	  3    /* SEED: 2 chars plus terminating NULL */

#define TRACE2_VERSION0  '2'   /* version[0] for TYPE_TRACEBUF2       */
#define TRACE2_VERSION1  '0'   /* version[1] for TYPE_TRACEBUF2       */

#define LOC_NULL_STRING  "--"  /* NULL string for location code field */

typedef struct {
        int     pinno;                 /* Pin number */
        int     nsamp;                 /* Number of samples in packet */
        double  starttime;             /* time of first sample in epoch seconds
                                          (seconds since midnight 1/1/1970) */
        double  endtime;               /* Time of last sample in epoch seconds */
        double  samprate;              /* Sample rate; nominal */
        char    sta[TRACE2_STA_LEN];   /* Site name (NULL-terminated) */
        char    net[TRACE2_NET_LEN];   /* Network name (NULL-terminated) */
        char    chan[TRACE2_CHAN_LEN]; /* Component/channel code (NULL-terminated)*/
        char    loc[TRACE2_LOC_LEN];   /* Location code (NULL-terminated) */
        char    version[2];            /* version field */
        char    datatype[3];           /* Data format code (NULL-terminated) */
        char    quality[2];            /* Data-quality field */
        char    pad[2];                /* padding */ 
} TRACE2_HEADER;

The version field is included to differentiate the TYPE_TRACEBUF2
message from the TYPE_TRACEBUF when data are stored without the
context of an Earthworm message logo. This is important for NCSN 
because our continuous archive consists of files of raw trace messages.
We have to be able to read a trace header and decide whether it 
contains the loc field or not.  The Earthworm tankplayer module has 
the same requirement; it reads a file containing raw trace messages
and will have to know whether to write them to the ring as 
TYPE_TRACEBUF or TYPE_TRACEBUF2 messages. 

The version field will be filled with 2 ASCII characters (no NULLs):
  TRACE2_VERSION0 = version[0] = main version number
  TRACE2_VERSION1 = version[1] = subversion number

________________________________________________________________________________


Adding location code to pick and coda messages. 2004/5/25:LDD
--------------------------------------------------------------

+ New messages are white-space delimited, and thus are variable length.

+ Pick sequence number range was increased to 0-999999.

+ Pick time is reported to thousandths of a second to support sample rates
  greater than 100sps.  Hypoinverse still has the hundredths of a second 
  limitation, but if we ever change locators, we'll be ready for increased
  precision.

+ Pick first motion (1-character) values: 
   'U' for Up (compression),
   'D' for Down (dilatation), 
   '?' for unknown (previous column-oriented format used ' ' for unknown).

+ Channel identifier is dot-delimited for better human readability.

+ A "blank" location code will be written as "--" (without quotes).

+ C library functions for converting the ascii pick/coda messages into 
  structures is available in rdpickcoda.c,h.

--------------------------------------------------------------

TYPE_PICK_SCNL

Sample TYPE_PICK_SCNL message (new field-oriented format):

8 4 3 2133 CMN.VHZ.NC.01 U1 19950831183134.900 953 1113 968\n

Field  Description
   1   MsgType (TYPE_PICK_SCNL=8, defined in earthworm_global.d)
   2   ModuleId
   3   InstId
   4   Pick sequence number (0-999999)
   5   channel identifier: Sta.Comp.Net.Loc
   6   two-character pick descriptor: char1=first motion (U,D,?)
                                      char2=pick quality (0-4, 0=best)
   7   pick time: yyyymmddhhmmss.ttt 
       (seconds to the thousandths to support sample rates > 100sps)
   8   amplitude of first  peak (digital counts)
   9   amplitude of second peak (digital counts)
  10   amplitude of third  peak (digital counts)
  \n   newline

For reference, sample TYPE_PICK2K message (column-oriented, 72 chars long):
 10  4  3 2133 CMN  NCVHZ U1  19950831183134.90     953    1113     968\n
0123456789 123456789 123456789 123456789 123456789 123456789 123456789 12

--------------------------------------------------------------

TYPE_CODA_SCNL

Sample TYPE_CODA_SCNL message (new field-oriented format):

9 4 3 2133 CMN.VHZ.NC.01 48 106 211 182 148 133 15\n

Field  Description
   1   MsgType (TYPE_CODA_SCNL=9, defined in earthworm_global.d)
   2   ModuleId
   3   InstId
   4   Pick sequence number (0-999999)
   5   channel identifier: Sta.Comp.Net.Loc
6-11   six coda 2-sec average absolute amplitudes (digital counts),
       listed in reverse chronological order (same as previous coda msg).  
  12   coda duration (seconds)
       Negative duration means that "noisy-trace" coda termination 
       method was used by the picker.  
  \n   newline

For reference, sample TYPE_CODA2K message (column-oriented, 79 characters long):
 11  4  3 2133 CMN  NCVHZ      48     106     211     182     148     133  15 \n
0123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789


________________________________________________________________________________


Adding location code to TYPE_EVENT* messages. 2005/3/17:LDD
------------------------------------------------------------

TYPE_EVENT_SCNL

This message type is used internally between eqproc/eqprelim and eqcoda in
the Earthworm "mega module" and is never output to an Earthworm ring. The
previous TYPE_EVENT2K message was column-oriented and the new TYPE_EVENT_SCNL
message is field-oriented.  The TYPE_EVENT_SCNL message contains an event
hypocenter line containing information from binder's TYPE_QUAKE messages,
followed by one line for each associated phase. Each phase line is a 
compilation of information from TYPE_PICK_SCNL, TYPE_CODA_SCNL, and TYPE_LINK 
messages, plus a data source supplied by the producing module.

Sample TYPE_EVENT_SCNL message:

20050317235045.380 36.558600 -121.114800 13.44 12 140 6.9 0.09 51157910 1
BVL VHZ NC -- U0 P 20050317235048.210 1515 1880 1992 30 59 64 171 124 174 15 W
BPI VHZ NC -- D0 P 20050317235048.450 674 1036 818 40 66 130 263 267 0 9 W
BBG VHZ NC -- D2 P 20050317235048.520 98 210 228 38 85 159 368 167 0 9 W
BEM VHZ NC -- D0 P 20050317235048.720 1334 1853 1112 38 60 137 199 253 0 9 W
BAV VHZ NC -- D0 P 20050317235048.790 228 205 101 29 51 52 0 0 0 5 W
BEH VHZ NC -- D0 P 20050317235049.090 144 238 137 34 80 111 197 166 0 9 W
BJO VHZ NC -- U0 P 20050317235049.680 569 638 535 35 59 84 148 142 0 9 W
BJC VHZ NC -- U0 P 20050317235050.610 211 495 319 27 50 49 89 129 125 11 W
BVY VHZ NC -- U1 P 20050317235052.220 185 541 294 32 83 0 0 0 0 3 W
JBZ VHZ NC -- D2 P 20050317235056.890 157 128 114 36 57 51 76 0 0 7 W

Hypocenter Line
Field  Description
   1   Origin time (yyyymmddhhmmss.ttt)
   2   Latitude (decimal degrees)
   3   Longitude (decimal degrees)
   4   Depth (km)
   5   Number of phases associated by binder
   6   Azimuthal Gap
   7   Distance to closes station (km)
   8   RMS (sec)
   9   Eventid from binder
  10   Version for event, supplied by module producing this message.
       If the module produces multiple TYPE_EVENT_SCNL msgs for each Eventid,
       then the version should be incremented.

Phase Line
Field  Description
   1   Station code
   2   Component code
   3   Network code
   4   Location code
   5   two-character pick descriptor: char1=first motion (U,D,?)
                                      char2=pick quality (0-4, 0=best)
   6   Phase descriptor from binder (P,Pg,Pn,S,Sg,Sn)
   7   pick time: yyyymmddhhmmss.ttt 
       (seconds to the thousandths to support sample rates > 100sps)
   8   amplitude of first  peak (digital counts)
   9   amplitude of second peak (digital counts)
  10   amplitude of third  peak (digital counts)
11-16  six coda 2-sec average absolute amplitudes (digital counts),
       listed in reverse chronological order.
  17   coda duration (seconds)
       Negative duration means that "noisy-trace" coda termination 
       method was used by the picker.
  18   Data source - a single character describing the source of the
       pick and coda information.  Examples: 'W' for local earthworm,
       'I' for imported from another institution.  

________________________________________________________________________________


Adding location code to station trigger messages. 2005/3/17:LDD
---------------------------------------------------------------

TYPE_CARLSTATRIG_SCNL

This is a field-oriented message produced by carlstatrig. The only change 
from the previous station trigger message is the addition of the location code 
field after the network code. Every time a station triggers, carlstatrig should
write two TYPE_CARLSTATRIG_SCNL messages, one when the station trigger turns
on, and another when the station trigger turns off.  Both messages have the
same format.

Sample TYPE_CARLSTATRIG_SCNL message:

JSP EHZ NC 01 1111165293.0000 1111165294.0000 14617 13.87

Field  Description
   1   Station code
   2   Component code
   3   Network code
   4   Location code
   5   Trigger ON time (sec since 1970)
   6   Trigger OFF time (sec since 1970, 0.0 while trigger is still ON)
   7   serial number for this station trigger (so ON and OFF messages
       can be matched up)
   8   ETA when the station trigger went ON. 
       ETA is the triggering parameter computed from STA, LTA and other things.
       A station trigger is ON when ETA > 0.0, OFF when ETA <= 0.0.


________________________________________________________________________________


Adding location code to triglist messages. 2005/3/17:LDD
--------------------------------------------------------

TYPE_TRIGLIST_SCNL

Triglist messages are produced by a number of different Earthworm modules 
and the details of how certain fields are filled vary from module to module.  
I'm not going to try to cover all the variations here. 

Here's a sample TYPE_TRIGLIST_SCNL message:

v2.0 EVENT DETECTED     20050308 20:47:02.71 UTC EVENT ID: 69000541 AUTHOR: 014024003:033052003

Sta/Cmp/Net/Loc   Date   Time                       start save       duration in sec.
---------------   ------ ---------------    ------------------------------------------
 GGP * NC -- P 20050308 20:47:03.45 UTC    save: 20050308 20:46:48.45       35
 GDX * NC * P 20050308 20:47:04.40 UTC    save: 20050308 20:46:48.45       35
 GPM * NC * P 20050308 20:47:05.01 UTC    save: 20050308 20:46:48.45       35
 GAX * NC * P 20050308 20:47:04.86 UTC    save: 20050308 20:46:48.45       35
 GAC * NC * P 20050308 20:47:05.18 UTC    save: 20050308 20:46:48.45       35
 GSS VHZ NC 01 P 20050308 20:47:05.47 UTC    save: 20050308 20:46:48.45       35
 NMC * NC * P 16000101 00:00:00.00 UTC    save: 20050308 20:46:48.45       35
 NFV * NC * P 16000101 00:00:00.00 UTC    save: 20050308 20:46:48.45       35
 NEA * NC * P 16000101 00:00:00.00 UTC    save: 20050308 20:46:48.45       35

Here are the differences between the previous triglist message and 
the new TYPE_TRIGLIST_SCNL:
1. added version field to the beginning of the EVENT line 
   Version is set to "v2.0" for the TYPE_TRIGLIST_SCNL message.
2. added location code field (just after the network code field) on the 
   station line. This field can contain the actual channel location code, 
   or "*" for wildcard.

Library functions for parsing the TYPE_TRIGLIST_SCNL message are contained in
parse_trig.c,h. These functions have been modified to recognize only 
TYPE_TRIGLIST_SCNL messages!


________________________________________________________________________________


Adding location code to station LP trigger messages. 2005/3/18:LDD
------------------------------------------------------------------

These messages are produced by evanstrig and consumed by evansassoc.
I don't know of any other modules that use them.

Sample TYPE_LPTRIG_SCNL message:

31 32 3 16 MGP VHZ NC 01 1111103996.770 B

Field  Description
   1   MsgType (TYPE_LPTRIG_SCNL=31, defined in earthworm_global.d)
   2   ModuleId
   3   InstId
   4   Channel pin number (legacy field)
   5   Station code
   6   Component code
   7   Network code
   8   Location code
   9   Trigger time (sec since 1970)
  10   Type of trigger (single character: N=normal, B=big)


________________________________________________________________________________


Adding location code to hypoinverse archive messages. 2005/3/18:LDD
-------------------------------------------------------------------

The hypoinverse archive format already includes a field for location code.
See details of the "station archive format" in Fred Klein's documentation:

ftp://ehzftp.wr.usgs.gov/klein/docs/shadow2000.pdf
ftp://ehzftp.wr.usgs.gov/klein/hyp2000/docs/hyp2000-1.0.pdf

Modules which produce and consume TYPE_HYP2000ARC messages have been modified
to fill and read the location code field.