NAME
ew2orb - Import waveform data from Earthworm into an orb
SYNOPSIS
ew2orb [-p pfname] orb
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
The
ew2orb module connects to one or more Earthworm export_generic
modules, importing waveform data from the requested sources. The module
is multithreaded, meaning that one instance can import data from several
different sources at once. The module is also dynamically reconfigurable,
which means that changes to the parameter file are monitored and
noticed automatically. There should be no need to stop and restart the program
after removing an old connection or adding a new one.
The
orb name to which to write data is specified on the command line. After
that, most of the
ew2orb configuration is in the
ew2orb parameter file,
named
ew2orb.pf by default. All data are written in MGENC packet format.
A sample parameter file is included below. The parameter
program_loglevel controls the overall level of logging output for the
program. The options for this setting are "quiet", "verbose", and
"veryverbose". The latter is meant for debugging purposes, and will
generate a great deal of output (several lines for each incoming
packet). The parameter calibration_database gives the name of a database
with calibration information for the incoming stations. Since Earthworm
waveform packets do not contain calibration data and the Antelope waveform
packets do contain calibration data, a database is necessary to
hold the calibration information. If this database is not found, ew2orb
will complain, and fill in the Antelope packets with null calibration
information. This database is also used for the 'segtype' field in the
Antelope packets. segtype is taken from the rsptype field of the
instrument table. calib and calper are taken from the corresponding fields
of the calibration table. Note that in order to make use of the instrument
table, the sensor table must also be present and have valid entries
for the incoming stations.
The bulk of the parameter file is contained in the 'import_from' array.
This array in turn contains one array for each data-import connection
desired. Each one of these input connections must have a name, which is
used to group the parameters for that connection in the import_from
array. This name may be chosen at user discretion (usually as a useful
mnemonic for the particular data connection). The name will be used in
a number of places throughout the program when labeling output messages.
Before describing in detail the contents of each import_from subarray,
we should note the 'defaults' array in the parameter file. This array
specifies the default parameters for Earthworm import connections.
If one of the parameters does not show up in the subarray describing
a particular connection, the value from the defaults array is used. Values in the
specific subarrays for each connection will override the defaults. A
description of the connection parameters follows:
OPTIONS
-
-p pfname
Specify an alternate parameter-file name for the ew2orb module.
The default parameter file is "ew2orb.pf".
FILES
PARAMETER FILE
calibration_database dbmaster/cnsn
program_loglevel verbose
defaults &Arr{
server_port 16010
send_heartbeat_sec 120
send_heartbeat_string alive
expect_heartbeat_sec 300
expect_heartbeat_string .*alive.*
my_inst INST_UNKNOWN
my_mod MOD_UNKNOWN
default_segtype V
select
reject
srcname_morph &Tbl{
}
timecorr &Arr{
}
}
import_from &Arr{
PGC_test &Arr{
server_ipaddress 139.142.67.7
send_heartbeat_sec 100
send_heartbeat_string KENTalive
srcname_morph &Tbl{
/CN_PFB_HHE/CN_TEST_XXE/
}
}
PGC_compressed &Arr{
server_ipaddress 139.142.67.7
server_port 16015
send_heartbeat_string KENTalive
}
Kent &Arr{
server_ipaddress 192.168.0.2
send_heartbeat_sec 100
send_heartbeat_string alive
loglevel quiet
timecorr &Arr{
AK_CNP_EHZ 0.27
}
}
}
EXAMPLE
This example shows the standard usage of directing the ew2orb module
at a local orb. All of the rest of the information ew2orb needs, for
example the locations of the Earthworm servers to connect to, is contained
in the parameter file.
% ./ew2orb :
ew2orb: entering 'verbose' mode
ew2orb: Reconfiguring ew2orb from parameter file
ew2orb: 'Kent':...ew2orb_import thread started
ew2orb: 'Kent': import thread Connected to remote export module
ew2orb: 'PGC_compressed':...ew2orb_import thread started
ew2orb: 'PGC_test':...ew2orb_import thread started
ew2orb: 'PGC_compressed': import thread Connected to remote export module
ew2orb: 'PGC_test': import thread Connected to remote export module
....
SEE ALSO
orbserver(1), orb2ew(1), earthworm(5)
BUGS AND CAVEATS
ew2orb and orb2ew replace the eworm2orb and orb2eworm programs, which
are deprecated.
There is no recovery mechanism in the Earthworm import/export_generic
protocol. Also, depending on the ring-buffer dynamics of the Earthworm
system on the sending side, it is possible for conditions
to occur where packets will be lost. There is no mechanism available on
which
ew2orb can rely in order to prevent this loss; if it happens, data
must be recovered by other means. One consequence of this is that
if import threads are stopped for reconfiguration, a small packet drop
will occur for that thread and data stream.
Received module numbers are translated according to the local contents
of earthworm.pf. If those do not match the translations at the remote
site, the names may be misleading in verbose output.
The translations of earthworm logo fields (institute, module, and type)
are set when first encountered and do not update even when the
underlying earthworm.pf parameter file changes. If changes are made
to these translations, the program must be restarted for them to be
recognized. Also, despite being specified in the earthworm.pf parameter
file, the INST_WILDCARD, MOD_WILDCARD, and TYPE_WILDCARD values are
hard-wired to zero as per Earthworm definition. The exception is if
one of the earthworm-logo numbers is not found and continually
shows up as, e.g., MOD_165. In this case the earthworm.pf parameter
file is checked upon each translation. Note that this can introduce
a small run-time inefficiency; it's advantageous to have translations
present in earthworm.pf for all modules, message types, and installations
encountered.
Because the select and reject subsetting is done on the receiving side,
bandwidth is used according to the number of packets being sent by the
remote export module, regardless of whether the ew2orb select and
reject expressions allow them to be put on the orb.
ew2orb will dynamically adjust to changes in the calibration_database.
However, if the pathname of the database changes,
ew2orb must be
restarted. Note also that if changes are made to calibration values using
dbe(1), sometimes one must quit the dbe application for the changes to be
noticed by
ew2orb.
The timecorr array allows waveform timestamps to be shifted forward
and backwards in time. The amounts are left to user discretion; no
limits are placed on the amount of shifting. Shifting data too far
into the future may cause a host of downstream problems.
Currently only station and channel name are used in looking up calibration
information in the stations database (net and loc codes are ignored).
AUTHOR
Dr. Kent Lindquist
Lindquist Consulting, Inc.
Antelope User Group Contributed Software