NAME
orb2ew - Export waveform data from an orb to Earthworm
SYNOPSIS
orb2ew [-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
orb2ew module provides one or more Earthworm export_generic style
server instances, to which import clients can connect to request data.
The module
is multithreaded, meaning that one instance can export data on several
ports 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 server or adding a new one.
The
orb name from which to read data is specified on the command line. After
that, most of the
orb2ew configuration is in the
orb2ew parameter file,
named
orb2ew.pf by default.
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 bulk of the parameter file is contained in the 'export_servers' array.
This array in turn contains one array for each data-export server
desired. Each one of these export servers must have a name, which is
used to group the parameters for that connection in the export_servers
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 subarray of the export_servers array,
we should note the 'defaults' array in the parameter file. This array
specifies the default parameters for Earthworm export 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:
-
server_ipaddress
This gives the IP address of the Earthworm server from which to export data.
The default is to leave this blank, in which case all network interfaces
on the machine are valid for connections. On a multi-homed host, users
may wish to restrict the outgoing IP addresses on which connections will
be accepted. This is accomplished by specifying the IP address (in
a.b.c.d dotted-decimal notation) of the desired network interface.
-
server_port
This is the TCP port-number on which a server thread is serving data.
-
send_heartbeat_sec
The orb2ew import module exchanges heartbeats with the remote import
module at regular intervals. This parameter specifies the interval, in seconds,
at which these heartbeats are sent by orb2ew.
-
send_heartbeat_string
The heartbeat sent out by orb2ew must be a string which matches the
value being expected by the remote import module.
-
expect_heartbeat_sec
This parameter describes, in seconds, how often to expect an incoming
heartbeat from the remote import module. Usually this value is set to
an amount of time notably longer than the actual import heartbeat interval,
to avoid unnecessary warning messages. If orb2ew does not receive
a heartbeat within this interval, it will issue a warning message and
continue.
-
export_heartbeat_string
This parameter is a regular expression (in the style of regex(5))
which the incoming heartbeat string must match.
-
select
This parameter is a string which is fed to the orbselect(3) call
after each orb connection is established. If the parameter is left
blank, no orbselect(3) call is made.
-
reject
This parameter is a string which is fed to the orbreject(3) call
after each orb connection is established. If the parameter is left
blank, no orbreject(3) call is made.
-
starttime
This parameter specifies a beginning time for data which should be
sent. If the string is blank, no time filtering is done. If the string
is specified in a format understood by str2epoch(3), the orbafter(3) routine
will be called to position the orbserver read pointer, and packets
before the specified time will be rejected. This parameter may also be used
to rewind the server to start at an earlier position in the orb.
-
timesort_queue_maxpkts
This parameter specifies the size of the packet-sorting queue. If this
parameter is nonzero, orb2ew attempts to sort packets into time order,
using the pktchannelpipe(3) routines [specifically, the
timesort_queue_maxpkts is sent as the maxpkts argument
to pktchannelpipe_new(3)].
-
my_inst
This is the Earthworm institution code for orb2ew to report itself
as when it sends out heartbeats. This institution code is translated
to an integer value by orb2ew, according to the contents of the
earthworm.pf parameter file (For more details, see the man page earthworm(5)).
-
my_mod
This is the Earthworm module code for orb2ew to report itself
as when it sends out heartbeats. This module code is translated
to an integer value by orb2ew, according to the contents of the
earthworm.pf parameter file (For more details, see the man page earthworm(5)).
-
my_type
This is the Earthworm type id number for the data format which orb2ew
should export. This type code is translated
to an integer value by orb2ew, according to the contents of the
earthworm.pf parameter file (For more details, see the man page earthworm(5)).
Currently the valid settings for this are TYPE_TRACEBUF and TYPE_TRACEBUF2.
-
loglevel
This the level of logging information for the export thread in
question to put out. The allowed values are "quiet", "verbose", and
"veryverbose". If this option is not specified, it defaults to the
value of program_loglevel. As with the other parameters, this can
be changed dynamically, which can be useful to turn on veryverbose output
for a connection on which the operator has a question, then turn
off veryverbose output after resolution.
-
select
Outgoing stations (orb source-names, i.e. net_sta_chan, before they're
translated to any new names) which match this regular expression will
be allowed to go out to the remote Earthworm module. The default, which
is to leave this blank, allows all sources on the orb to go out.
-
reject
Outgoing stations (orb source-names, i.e. net_sta_chan, before they're
translated to any new names) which match this regular expression will
be rejected and not allowed to go out over the export connection. The default,
which is to leave this blank, allows all sources on the orb to go out.
-
max_tracebuf_size
This parameter constrains the maximum size of packets to be sent without
modification (how actually to handle packets larger than max_tracebuf_size is
determined by the parameter large_tracebuf_handling, q.v.). If max_tracebuf_size
is not set, it defaults to the value compiled into the code, currently
4096 bytes.
-
large_tracebuf_handling
If the total size of the outgoing trace-buf is larger than the
max_tracebuf_size value, the large_tracebuf_handling parameter
controls what happens to it. This parameter has several available modes:
-
send
This setting for large_tracebuf_handling, the default, sends packets to
Earthworm regardless of whether they are above or below the size threshold.
-
reject
This setting rejects packets which are too large for Earthworm (as determined
by the current setting of max_tracebuf_size), emitting a complaint to the
log file.
-
reject_silent
This is the same as "reject", however the
complaint message to the log file will be suppressed.
-
split N
This setting for large_tracebuf_handling splits packets into smaller
sub-packets of N samples each before sending them (Note that the decision
to split packets is still driven by the setting of max_tracebuf_size, thus one
can still have packets sent with more than N samples if their total size is
less than max_tracebuf_size).
-
pins
The pins array specifies optional Earthworm pin-numbers for individual station
channels. Each entry should be listed as NET_STA_CHAN followed by
the desired pin number. If no pin number is specified for a given
channel, a pin-number of 0 will be used.
OPTIONS
-
-p pfname
Specify an alternate parameter-file name for the orb2ew module.
The default parameter file is "orb2ew.pf".
FILES
PARAMETER FILE
program_loglevel verbose
defaults &Arr{
send_heartbeat_sec 120
send_heartbeat_string alive
expect_heartbeat_sec 300
expect_heartbeat_string .*alive.*
select
reject
my_inst INST_UNKNOWN
my_mod MOD_UNKNOWN
my_type TYPE_TRACEBUF
starttime
timesort_queue_maxpkts 0
max_tracebuf_size 4096
large_tracebuf_handling send
}
export_servers &Arr{
PGC_test &Arr{
server_ipaddress # blank = use all interfaces on machine
server_port 16015
send_heartbeat_sec 100
send_heartbeat_string alive
}
}
pins &Arr{
CN_BBB_BHE 1
CN_BBB_BHN 2
CN_BBB_BHZ 3
CN_PGC_BHE 4
CN_PGC_BHN 5
CN_PGC_BHZ 6
CN_TXB_EHZ 7
}
SEE ALSO
orbserver(1), ew2orb(1), earthworm(5)
BUGS AND CAVEATS
orb2ew and ew2orb replace the eworm2orb and orb2eworm programs, which
are deprecated.
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 the Earthworm definitions. The exception is that if
one of the Earthworm-logo numbers is not found (and thus continually
shows up as, e.g., MOD_165), 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.
The channels_select and channels_reject tables of pktchannelpipe_new
are not passed through (there is no support for these in orb2ew.pf),
since the orb2ew select and reject expressions already cover that function.
The queue codes from the pktchannelpipe callback are currently ignored.
One should note the wait-time tradeoff involved in sorting out-of-order
data. The queue should not be made too large or data will be delayed
proportionately when packets arrive out of order or are missing.
The channel codes for Earthworm TYPE_TRACEBUF2 messages are four characters
at maximum, shorter than those for CSS3.0. If longer channel names are encountered
on the orbserver, they will be bluntly truncated to fit.
If the
large_tracebuf_handling parameter is set to split the packet
into a certain number of samples, and that number results in a sub-packet
that is still larger than the configured
max_tracebuf_size, the entire
packet will be rejected with a warning message.
The parameter-file is dynamically re-read to detect configuration changes. However,
if an optional parameter is added, then entirely removed from the parameter file,
orb2ew wil not notice, because it has come to expect that parameter to be
present. In some sense this could be considered a bug; certainly it could be circumvented
with yet more programming, but the marginal value is questionable. Once you add
optional parameters to the parameter file, just keep them in there for the duration
of the run (you may change them as you wish and the dynamic updates will be
made in the running executable).
AUTHOR
Kent Lindquist
Lindquist Consulting, Inc.
Antelope User Group Contributed Software