Changes between Version 2 and Version 3 of rcv_ew


Ignore:
Timestamp:
03/18/12 17:08:57 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • rcv_ew

    v2 v3  
    4747 5. user_shutdown() invoked by RCV and STATION as part of the process termination. 
    4848 
     49 
     50=== RCV COMMAND-LINE SWITCHES === 
     51 
     52The RCV command line is the only command line listed for this module in startstop's configuration file. This command line must contain all of the switches for both RCV and STATION, as well as the name of the Earthworm configuration file. RCV spawns STATION, passing it the complete list of command switches that it started with. STATION then calls the user_proc_cmd function and passes it the configuration file name. Each process ignores the other's switches when it configures itself. Here we list only the command line switches used by RCV: 
     53{{{ 
     54  -tcp          Use TCP/IP socket to NSN3.CR.USGS.GOV to get data. 
     55                Use of the -tcp switch excludes use of the -i switch. 
     56 
     57  -i pathname   Use the pathname as the device to obtain serial data from 
     58                (-i /dev/ttya).  Use of the -i switch excludes use of 
     59                the -tcp switch. 
     60 
     61  -o path       Open file "path" for writing log output to. The size of this 
     62                file is unbounded. If -o is omitted, all log output will be 
     63                written to stdout. 
     64 
     65  -!            Turn on debugging print statements (usually used only in testing). 
     66 
     67  -$            Turn on force rollback flag (usually used only in testing). 
     68}}} 
     69 
     70=== STATION COMMAND-LINE SWITCHES === 
     71 
     72The RCV command line is the only command line listed for this module in startstop's configuration file. This command line must contain all of the switches for both RCV and STATION, as well as the name of the Earthworm configuration file. RCV spawns STATION, passing it the complete list of command switches that it started with. Then STATION calls the user_proc_cmd() function and passes it the configuration file name. Each process ignores the other's switches when it configures itself. Here we list only the command line switches used by STATION: 
     73{{{ 
     74  -# Nch        Send multiple channels to one STATION, Nch is max # channels. 
     75                STATION will use the last channel slot for any new channel 
     76                that comes in after all of the channel slots are full. Since 
     77                unexpected channels sometimes slip thru from Golden, it is 
     78                recommended that Nch be greater than the number of channels 
     79                you have arranged to receive. 
     80                Under Earthworm, this argument is required. 
     81 
     82  -partial      Call user_proc with incremental updates on "partial" update 
     83                packets. The default behavior is to wait for a complete 
     84                USNSN packet to come in before submitting it to user_proc. 
     85                This allows NSN LH* channels to be processed every two 
     86                minutes or so instead of about once per 20-40 minutes. 
     87                Under Earthworm, the -partial argument must be omitted. 
     88 
     89  -s            Open a log file for each STATION process. The name of the 
     90                log file is based on the station name being processed by each 
     91                instance of STATION. If -# is used, the log file will be named 
     92                "station.log". The file(s) will be written in the directory 
     93                from which RCV/STATION was started (under Earthworm, this will 
     94                be the EW_PARAMS directory). If the -s switch omitted, no log 
     95                file will be created; all log output will be written to stdout. 
     96                NOTE: the log file size is unbounded; it tends to get very 
     97                      large very quickly. 
     98                      We recommend running without -s argument. 
     99 
     100  -e config     Names the Earthworm configuration file "config" to be read 
     101                in the user_proc_cmd() function.  This switch is valid only 
     102                in the Earthworm impletmentation of rcv_ew. 
     103                Under Earthworm, this argument is required. 
     104 
     105  -dbg          Turns on debugging (not usually used by users). 
     106}}} 
     107 
     108=== Earthworm Configuration File === 
     109==== FUNCTIONAL COMMAND LISTING ==== 
     110The Earthworm configuration file name is given in the "-e" command line switch of STATION. The -e switch is actually processed in the user_proc_cmd() function, and the configuration file itself is read by rcv_ew_config(). The source code for both of these functions resides in the file user_proc_ew.c. Below are the commands recognized by rcv_ew_config, grouped by the function they influence. 
     111 
     112In the config file, lines may begin with a valid rcv_ew command (listed below) or with one of 2 special characters: 
     113{{{ 
     114#  marks the line as a comment (example: # This is a comment). 
     115 
     116@  allows control files to be nested; one control file can be 
     117   accessed from another with the command "@" followed by 
     118   a string representing the path name of the next control file 
     119   (example: @model.d). 
     120}}} 
     121 
     122Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). 
     123{{{ 
     124        Earthworm system setup: 
     125                HeartBeatInt            required 
     126                MyModuleId              required 
     127                RingName                required 
     128 
     129        Waveform Input/Output: 
     130                AcceptSCN               required 
     131                PacketLatency           required 
     132                MaxSamplePerMsg         required 
     133                MaxSilence              required 
     134 
     135        Output Control: 
     136                LogFile                 required 
     137                Debug 
     138}}} 
     139 
     140==== ALPHABETIC COMMAND LISTING & DESCRIPTION ==== 
     141In the following section, all Earthworm configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and examples commands are listed after each command description. 
     142 
     143The following list is organized by: 
     144 
     145command [argument here] 
     146 
     147 
     148'''AcceptSCN [site comp net pinno]'''[[BR]] 
     149Preocessed by: rcv_ew_config[[BR]] 
     150Functio: Waveform input 
     151 
     152Describes one of the channels of waveform data that rcv_ew expects to receive from the USNSN. site is the channel's SEED site code (up to 6 chars), comp is the SEED component code (up to 8 chars), and net is the channel's network code (up to 8 chars). pinno is a number (0-32767) which will be included in the "pinno" field of the Earthworm-formatted waveform message header. This number will be meaningful only to the local installation (other installations may apply a different pinno to the same data stream). You must list an "AcceptSCN" command for each channel that you expect to get from the USNSN. Rcv_ew will ignore data from any channel that is not listed in an "AcceptSCN" command, issuing an error message that it is doing so. The total number of "AcceptSCN" commands that can be listed is limited to "Nch" as set in STATION's "-# Nch" command-line switch. 
     153{{{ 
     154Default:  none 
     155Example:  AcceptSCN HWUT BHZ US 999 
     156}}} 
     157 
     158'''Debug'''[[BR]] 
     159Processed by: rcv_ew_config[[BR]] 
     160Function: output 
     161 
     162This optional command turns on debugging statements, printed both to the screen and to the log file. To turn off debugging statements, omit this command (or comment it out). 
     163{{{ 
     164Default:  no debugging statements 
     165}}} 
     166 
     167'''!HeartBeatInt [nsec]'''[[BR]] 
     168Processed by: rcv_ew_config[[BR]] 
     169Function: Earthworm setup 
     170 
     171Sets the minimum number of seconds nsec between TYPE_HEARTBEAT messages issued by rcv_ew. The heartbeat function (user_heart_beat) is entered whenever data or keepalive messages are received from Golden. A heartbeat will be issued only if at least nsec seconds have elapsed since the last heartbeat. Since data arrives at irregular intervals, the actual heartbeat interval will be irregular. At a minimum, Golden sends a keepalive once every minute. To guarantee that rcv_ew issues a heartbeat for every keepalive received, set nsec to something less than 60 seconds (even so, an interval between heartbeats from a properly operating rcv_ew could be as long as nsec+60-1 seconds). 
     172{{{ 
     173Default:  none 
     174Example:  HeartBeatInt 30 
     175}}} 
     176 
     177'''!LogFile [switch]'''[[BR]] 
     178Processed by: rcv_ew_config[[BR]] 
     179Function: output 
     180 
     181Sets the on-off switch for writing an Earthworm log file to disk. If switch is 0, no log file will be written. If switch is 1, rcv_ew will write a daily log file(s) called rcv_ewxx.log_yymmdd where xx is rcv_ew's module id (set with "MyModuleId" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).  
     182 
     183NOTE: this log file contains information from only the Earthworm portion of rcv_ew. It is separate from the log files written by the USNSN code, RCV and STATION (see -o and -s command-line switches). 
     184{{{ 
     185Default:  none 
     186}}} 
     187 
     188'''!MaxSamplePerMsg [nsamp]'''[[BR]] 
     189Processed by: rcv_ew_config[[BR]] 
     190Function: Waveform output 
     191 
     192Sets the maximum number of samples, nsamp, to pack into each outgoing TYPE_TRACEBUF message. Each sample is stored as a 4-byte integer, in local byte order. The byte-order is recorded in the "datatype" field of the tracebuf header. An nsamp of 1008 will yield the largest allowed TYPE_TRACEBUF message (64 byte header + 4032 bytes of data). Some TYPE_TRACEBUF messages output by rcv_ew will contain fewer than nsamp data samples. 
     193{{{ 
     194Default:  none 
     195Example:  MaxSamplePerMsg 500 
     196}}} 
     197 
     198'''!MaxSilence [nmin]'''[[BR]] 
     199Processed by: rcv_ew_config[[BR]] 
     200Function: Waveform I/O 
     201 
     202Sets a time limit for reporting silent stations (long data gaps). If rcv_ew does not receive any data for a given channel for nmin minutes, it will issue an error message saying "No data from S C N in xx minutes." Rcv_ew will continue to issue an error every additional nmin minutes that no data comes in. When rcv_ew starts receiving data for that channel again, it will issue an "un-error" message saying "Once again receiving data from S C N." If nmin is zero, rcv_ew will not issue any messages about long data gaps. 
     203{{{ 
     204Example:  MaxSilence 240 
     205}}} 
     206 
     207'''!MyModuleId [mod_id]'''[[BR]] 
     208Processed by: rcv_ew_config[[BR]] 
     209Function: Earthworm setup 
     210 
     211Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number. 
     212{{{ 
     213Default:  none 
     214Example:  MyModuleId MOD_RCV_EW 
     215}}} 
     216 
     217'''!PacketLatency [npkt]'''[[BR]] 
     218Processed by: rcv_ew_config[[BR]] 
     219Function: Waveform I/O 
     220 
     221Sets the number of USNSN packets to buffer for each channel before releasing one. This buffering gives rcv_ew a chance to resequence packets after a rollback (when packets are re-sent due to detected communication problems), allowing corrected data instead of possibly corrupted data to be released. npkt must be between 0 and 8, inclusive. Rcv_ew will not output any data for a given channel until after npkt packets have been received. Once the buffer is full, rcv_ew will release the oldest packet on receipt of a new, in-sequence packet. If rcv_ew gets an out-of-sequence packet with an earlier-than- expected timestamp (a rollback packet), it looks through that channel's buffer for a packet with an identical sequence number. If such a packet is found, rcv_ew overwrites it with the newly received packet. Otherwise, rcv_ew issues a "Rollback cannot be used" error, and discards the new packet. If rcv_ew gets an out-of-sequence packet with a later-than-expected timestamp, it issues a "Gap prior to seq=x" error, and buffers the new packet for later release. When rcv_ew gets a packet marked "end-of-trace-segment" (triggered data), it releases all packets in the buffer for that channel (who knows how long it will be until the next trigger occurs?). If npkt is set to zero, no packets will be buffered; they will be released as soon as they are received and any rollbacks will be ignored. 
     222{{{ 
     223Example:  PacketLatency 2 
     224}}} 
     225 
     226'''!RingName [ring]'''[[BR]] 
     227Processed by: rcv_ew_config[[BR]] 
     228Function: Earthworm setup 
     229 
     230Tells rcv_ew which shared memory region to use for output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. 
     231{{{ 
     232Example:  RingName WAVE_RING 
     233}}} 
     234 
     235==== SEED CHANNEL NAME FILE ==== 
     236 
     237RCV and STATION (as well as other USNSN and IRIS codes) use get_name() to get SEED names for channels. This function requires that a file named nsnstation2.dat reside in the directory in which the program was started. A sample of this file is included in rcv_ew's source directory .../vX.X/src/rcv. The best way to get the most up-to-date station list from Golden is to use the autodrm. Send a mail message to autodrm@gldfs.cr.usgs.gov with the body: 
     238{{{ 
     239BEGIN 
     240CLIST 
     241STOP 
     242}}} 
     243The returned mail can then be saved as a text file and named nsnstation2.dat. For rcv_ew to run correctly, a copy of nsnstation2.dat must be placed in the EW_PARAMS directory. 
     244 
     245==== SAMPLE COMMAND-LINES FOR STARTING RCV_EW ==== 
     246 
     247Below are three example command lines that you could include in the startstop configuration file to run rcv_ew as an Earthworm module. A sample Earthworm configuration file (rcv_ew.d) is shown below. 
     248 
     249 A. This command contains the minimum set of required command-line switches to start up rcv_ew. It will also yield the minimum disk-file output, with most messages being written to stdout: 
     250{{{ 
     251        "rcv -tcp -# 8 -e rcv_ew.d" 
     252}}} 
     253 
     254 B. This command gives rcv its own log file in the log directory: 
     255{{{ 
     256        "rcv -tcp -o ../log/rcv.log -# 19 -e rcv_ew.d" 
     257}}} 
     258 
     259 C. This command will yield huge log files, with debugging turned on for rcv and station (and possibly the Earthworm rcv_ew too): 
     260{{{ 
     261        "rcv -tcp -o ../log/rcv.log -! -# 12 -s -dbg -e rcv_ew.d" 
     262}}} 
     263 
     264==== SAMPLE EARTHWORM CONFIGURATION FILE ==== 
     265 
     266{{{ 
     267# rcv_ew.d 
     268# 
     269# RCV under Earthworm is started by startstop, and given the command line 
     270#     found in startstop.d.  That's where RCV get's its customary command 
     271#     line arguments. 
     272# The file here is read by the "user_proc" routines, which determine RCV's 
     273#     identity to Earthworm. 
     274 
     275 MyModuleId       MOD_RCV_EW   # module id for this program, 
     276 RingName         WAVE_RING    # transport ring to use for input/output, 
     277 HeartBeatInt     30           # Heartbeat interval in seconds, 
     278 LogFile          1            # If 0, don't write logfile at all, 
     279 MaxSamplePerMsg  240          # #samples in largest message we'll ever create 
     280 PacketLatency    2            # #packets to buffer before releasing 
     281                               #    (to handle rollbacks) 
     282 
     283# Debug    # uncomment to write debug messages 
     284 
     285# Monitor the time since the last packet received for each site/comp/net. 
     286#  if MaxSilence  > 0, rcv_ew will issue a message to statmgr when it has not 
     287#                      seen a packet for MaxSilence minutes.  If it has issued 
     288#                      such a message, it will also issue another message when it 
     289#                      starts receiving data for the SCN again. 
     290#  if MaxSilence <= 0, rcv_ew will not monitor the time since last packet. 
     291# 
     292 MaxSilence  600    # number of minutes to wait before complaining that 
     293                    # no new data is being received for a given SCN 
     294 
     295# List each site/comp/net that you expect from Golden in a "AcceptSCN" command. 
     296#     If rcv_ew sees an SCN which is not listed here, it will be ignored. 
     297#     On each line after the SCN, list a pinnumber to use for this SCN. 
     298 
     299#          site comp net pinno 
     300AcceptSCN  LPAZ BHZ  GT  6019 
     301AcceptSCN  LPAZ BHN  GT  6020 
     302AcceptSCN  LPAZ BHE  GT  6021 
     303AcceptSCN  LPAZ LHZ  GT  6022 
     304AcceptSCN  LPAZ LHN  GT  6023 
     305AcceptSCN  LPAZ LHE  GT  6024 
     306}}} 
     307 
    49308== Helpful Hints ==