Rcv_ew is a composite Earthworm module. It is made up of two USNSN programs (RCV and STATION, written and maintained by Dave Ketchum) that call a set of user functions (written by Lynn Dietz) which contain all the Earthworm-specific code. RCV handles the communication with the USNSN in Golden, receiving USNSN packets via a TCP/IP socket or a satellite. RCV spawns the STATION process at the end of a pipe and passes data packets to it. STATION processes the data packets and handles all the Earthworm communications by calls to the user functions. RCV and STATION are configured with command-line switches. The Earthworm user functions are configured with an Earthworm-style configuration file. In the following sections, we describe the configuration options for the components of rcv_ew:
Page Index:
The 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:
-tcp Use TCP/IP socket to NSN3.CR.USGS.GOV to get data.
Use of the -tcp switch excludes use of the -i switch.
-i pathname Use the pathname as the device to obtain serial data from
(-i /dev/ttya). Use of the -i switch excludes use of
the -tcp switch.
-o path Open file "path" for writing log output to. The size of this
file is unbounded. If -o is omitted, all log output will be
written to stdout.
-! Turn on debugging print statements (usually used only in testing).
-$ Turn on force rollback flag (usually used only in testing).
The 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:
-# Nch Send multiple channels to one STATION, Nch is max # channels.
STATION will use the last channel slot for any new channel
that comes in after all of the channel slots are full. Since
unexpected channels sometimes slip thru from Golden, it is
recommended that Nch be greater than the number of channels
you have arranged to receive.
Under Earthworm, this argument is required.
-partial Call user_proc with incremental updates on "partial" update
packets. The default behavior is to wait for a complete
USNSN packet to come in before submitting it to user_proc.
This allows NSN LH* channels to be processed every two
minutes or so instead of about once per 20-40 minutes.
Under Earthworm, the -partial argument must be omitted.
-s Open a log file for each STATION process. The name of the
log file is based on the station name being processed by each
instance of STATION. If -# is used, the log file will be named
"station.log". The file(s) will be written in the directory
from which RCV/STATION was started (under Earthworm, this will
be the EW_PARAMS directory). If the -s switch omitted, no log
file will be created; all log output will be written to stdout.
NOTE: the log file size is unbounded; it tends to get very
large very quickly.
We recommend running without -s argument.
-e config Names the Earthworm configuration file "config" to be read
in the user_proc_cmd() function. This switch is valid only
in the Earthworm impletmentation of rcv_ew.
Under Earthworm, this argument is required.
-dbg Turns on debugging (not usually used by users).
The 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.
In the config file, lines may begin with a valid rcv_ew command (listed below)
or with one of 2 special characters:
In 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.
RCV 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:
Below 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.
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:
3.1 FUNCTIONAL COMMAND LISTING
Command names must be typed in the control file exactly as shown in this
document (upper/lower case matters!).
# marks the line as a comment (example: # This is a comment).
@ allows control files to be nested; one control file can be
accessed from another with the command "@" followed by
a string representing the path name of the next control file
(example: @model.d).
Earthworm system setup:
HeartBeatInt required
MyModuleId required
RingName required
Waveform Input/Output:
AcceptSCN required
PacketLatency required
MaxSamplePerMsg required
MaxSilence required
Output Control:
LogFile required
Debug
3.2 ALPHABETIC COMMAND LISTING & DESCRIPTION
command arg1 processed by function
AcceptSCN site comp net pinno rcv_ew_config Waveform input
Describes 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.
Default: none
Example: AcceptSCN HWUT BHZ US 999
Debug rcv_ew_config output
This 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).
Default: no debugging statements
HeartBeatInt nsec rcv_ew_config Earthworm setup
Sets 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).
Default: none
Example: HeartBeatInt 30
LogFile switch rcv_ew_config output
Sets 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).
NOTE: 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).
Default: none
MaxSamplePerMsg nsamp rcv_ew_config Waveform output
Sets 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.
Default: none
Example: MaxSamplePerMsg 500
MaxSilence nmin rcv_ew_config Waveform I/O
Sets 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.
Example: MaxSilence 240
MyModuleId mod_id rcv_ew_config Earthworm setup
Sets 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.
Default: none
Example: MyModuleId MOD_RCV_EW
PacketLatency npkt rcv_ew_config Waveform I/O
Sets 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.
Example: PacketLatency 2
RingName ring rcv_ew_config Earthworm setup
Tells 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.
Example: RingName WAVE_RING
4. SEED CHANNEL NAME FILE
BEGIN
The 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.
CLIST
STOP
5. SAMPLE COMMAND-LINES FOR STARTING RCV_EW
"rcv -tcp -# 8 -e rcv_ew.d"
B. This command gives rcv its own log file in the log directory:
"rcv -tcp -o ../log/rcv.log -# 19 -e rcv_ew.d"
C. This command will yield huge log files, with debugging turned on for
rcv and station (and possibly the Earthworm rcv_ew too):
"rcv -tcp -o ../log/rcv.log -! -# 12 -s -dbg -e rcv_ew.d"
6. SAMPLE EARTHWORM CONFIGURATION FILE
# rcv_ew.d
#
# RCV under Earthworm is started by startstop, and given the command line
# found in startstop.d. That's where RCV get's its customary command
# line arguments.
# The file here is read by the "user_proc" routines, which determine RCV's
# identity to Earthworm.
MyModuleId MOD_RCV_EW # module id for this program,
RingName WAVE_RING # transport ring to use for input/output,
HeartBeatInt 30 # Heartbeat interval in seconds,
LogFile 1 # If 0, don't write logfile at all,
MaxSamplePerMsg 240 # #samples in largest message we'll ever create
PacketLatency 2 # #packets to buffer before releasing
# (to handle rollbacks)
# Debug # uncomment to write debug messages
# Monitor the time since the last packet received for each site/comp/net.
# if MaxSilence > 0, rcv_ew will issue a message to statmgr when it has not
# seen a packet for MaxSilence minutes. If it has issued
# such a message, it will also issue another message when it
# starts receiving data for the SCN again.
# if MaxSilence <= 0, rcv_ew will not monitor the time since last packet.
#
MaxSilence 600 # number of minutes to wait before complaining that
# no new data is being received for a given SCN
# List each site/comp/net that you expect from Golden in a "AcceptSCN" command.
# If rcv_ew sees an SCN which is not listed here, it will be ignored.
# On each line after the SCN, list a pinnumber to use for this SCN.
# site comp net pinno
AcceptSCN LPAZ BHZ GT 6019
AcceptSCN LPAZ BHN GT 6020
AcceptSCN LPAZ BHE GT 6021
AcceptSCN LPAZ LHZ GT 6022
AcceptSCN LPAZ LHN GT 6023
AcceptSCN LPAZ LHE GT 6024
Contact: Questions? Issues? Subscribe to the Earthworm Google Groups List.
Updated 16 April 1998