• Antelope Release 5.5 Linux 2.6.32-220.el6.x86_64 2015-04-21

 

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

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
Printer icon