seiscomp-training/share/doc/seiscomp/html/_sources/apps/scimex.rst.txt

.. highlight:: rst

.. _scimex:

######
scimex
######

**SeisComP event exchange between two systems.**


Description
===========

scimex manages the |scname| object exchange between two or more different SeisComP systems in
real time. scimex may import or export the data to one or several systems. In
contrary to :ref:`scimport` the exchange of the |scname| objects is event based.
This means no messages will be exchanged until the exporting system has produced
an event.

By default all objects (picks, amplitudes, origins, arrivals, station
magnitudes, magnitudes, magnitude references) are transferred to the other
system. The user can define filters at both the sender and the receiver, to
limit the events for which objects are transferred. Possible filter parameters
are the event location, magnitude, arrival count and agency. scimex supports
two modi: *import* and *export*. In export mode scimex collects all objects
relevant for an event (e.g. picks, amplitudes, origins, magnitudes) from
scmaster's message groups at the source and checks if the filter criteria
match. Once the criteria are fulfilled, the whole package of objects is send
to the scmaster IMPORT group of the receiving system.

At the receiving |scname| system an instance of scimex runs in import mode. It
fetches the whole event information from its own IMPORT group, checks the local
filter criteria of the system and sends the collected objects to the different
message groups, e.g. Pick, Amplitude, Magnitude, Location. In export mode
several recipients can be defined and for each recipient individual filters
can be set. To run several instances of scimex on one system, aliases have to
be defined, e.g. for import:

.. code-block:: sh

   seiscomp alias create scimex_import scimex

and for export:

.. code-block:: sh

   seiscomp alias create scimex_export scimex

Then the configuration can be split into scimex_import.cfg and
scimex_export.cfg.


Examples
========

For a push-type configuration, in which the exporting server must be able to
connect to the messaging server on the receiving host. On the receiving host:

scimex_import.cfg

.. code-block:: sh

   connection.username = scimexIm
   connection.server = localhost

   mode = IMPORT

   cleanupinterval = 86400

   importHosts = import1

   criteria.world.longitude = -180:180
   criteria.world.latitude = -90:90
   criteria.world.magnitude = 1:9
   criteria.world.agencyID = ""
   criteria.world.arrivalcount = 15

   hosts.import1.address = localhost
   # The criterion "world" has been defined above
   hosts.import1.criteria = world
   # optional and true per default
   hosts.import1.filter = false
   # optional and true per default
   hosts.import1.useDefinedRoutingTable = true
   hosts.import1.routingtable = Pick:IMPORT,StationAmplitude:IMPORT,
                                  Origin:LOCATION,Arrival:LOCATION,
                                  StationMagnitude:MAGNITUDE,
                                  Magnitude:MAGNITUDE,
                                  StationMagnitudeContribution:MAGNITUDE,
                                  OriginReference:EVENT,Event:EVENT


In this example, Pick and StationAmplitude objects are sent to the
receiving system's IMPORT group to avoid interfering with the receiving system's
picking.

On the sending system, only those events with a high enough magnitude
and enough arrivals, and with the AgencyID "GFZ" are exported:
scimex_export.cfg

.. code-block:: sh

   connection.username="scimexEx"
   connection.server = localhost

   mode = EXPORT

   cleanupinterval = 7200
   exportHosts = exp1, exp2

   # Match everything with magnitude above or equal 5
   # and with more than 25 phases which comes from
   # agency GFZ.
   criteria.globalM5.latitude     = -90:90
   criteria.globalM5.longitude    = -180:180
   criteria.globalM5.magnitude    = 5:10
   criteria.globalM5.arrivalcount = 25
   criteria.globalM5.agencyID     = GFZ

   # Export to a system which still runs a very old version. The
   # messages need to be converted.
   hosts.exp1.address = 192.168.0.3
   hosts.exp1.criteria = globalM5
   hosts.exp1.conversion = imexscdm0.51

   hosts.exp2.address = 192.168.0.4
   hosts.exp2.criteria = globalM5


.. _scimex_configuration:

Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/scimex.cfg`
| :file:`etc/global.cfg`
| :file:`etc/scimex.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/scimex.cfg`

scimex inherits :ref:`global options<global-configuration>`.



.. confval:: mode

   Type: *string*

   Mode of operation. Options are IMPORT or EXPORT.


.. confval:: cleanupinterval

   Type: *double*

   Unit: *s*

   Cache lifetime for objects.


.. confval:: subscriptions

   Type: *list:string*

   Only used in export mode. A list of message groups to subscribe.


.. confval:: conversion

   Type: *string*

   Used only in import mode. It defines the source format of the
   messages that need to be converted. Currently the import of
   SeisComP datamodel version 0.51 \(imexscdm0.51\)
   is supported which was used in release Barcelona \(2008\).


.. confval:: exportHosts

   Type: *list:string*

   A list of hosts profiles to be considered for exporting.
   These are used in hosts.\$name directives
   \(see below\) to define addresses, filter criteria, etc.
   applicable to each recipient.


.. confval:: importHosts

   Type: *list:string*

   A list of hosts profiles to be considered for importing.
   These are used with hosts.\$name directives similarly to
   exportHosts.


.. note::

   **criteria.$name.\***
   *A definition of an event filter.*
   $name is a placeholder for the name to be used.


.. confval:: criteria.$name.latitude

   Type: *tuple:double*

   Pair of doubles that defines the latitude range.
   Example: \-90:90.


.. confval:: criteria.$name.longitude

   Type: *tuple:double*

   Pair of doubles that defines the longitude range.
   Example: \-180:180.


.. confval:: criteria.$name.magnitude

   Type: *tuple:double*

   Pair of doubles that defines the magnitude range.
   Example: 3:10.


.. confval:: criteria.$name.arrivalcount

   Type: *int*

   Number of minimum arrivals.


.. confval:: criteria.$name.agencyID

   Type: *list:string*

   White list of AgencyIDs \(the agency identifier which
   appears in the objects sent over the export\-import link\).


.. note::

   **hosts.$name.\***
   *A sink definition used for either import or export.*
   $name is a placeholder for the name to be used.


.. confval:: hosts.$name.address

   Type: *string*

   Address of a sink, as a host name with an optional port
   number e.g. 'address \= 192.168.1.1' or
   'address \= somewhere.com:4803'


.. confval:: hosts.$name.criteria

   Type: *string*

   Defining filter criteria name for sink, e.g. criteria \=
   world\-xxl. The criteria must be defined in the criteria.
   \* configuration lines.


.. confval:: hosts.$name.filter

   Default: ``true``

   Type: *boolean*

   Enable\/disable filtering based on defined criteria.
   If set to false, all events will pass, even if one
   or more criteria are defined.


.. confval:: hosts.$name.conversion

   Type: *string*

   Optional target format for export.


.. confval:: hosts.$name.useDefinedRoutingTable

   Default: ``false``

   Type: *boolean*

   Enable\/disable defined routing tables.


.. confval:: hosts.$name.routingTable

   Type: *list:string*

   Defining routing tables in the meaning of mapping
   objects to message groups. Example: Pick:NULL,
   StationAmplitude:NULL, Origin:LOCATION,
   StationMagnitude: MAGNITUDE, NetworkMagnitude:MAGNITUDE,
   MagnitudeReference:MAGNITUDE, OriginReference:EVENT,
   Event:EVENT. Specifying NULL for the message group causes
   messages to be thrown away\/dropped\/discarded.



Command-Line Options
====================

.. program:: scimex

:program:`scimex [options]`


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file arg

   Use alternative configuration file. When this option is
   used the loading of all stages is disabled. Only the
   given configuration file is parsed and used. To use
   another name for the configuration create a symbolic
   link of the application or copy it. Example:
   scautopick \-> scautopick2.

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself
   and doesn't need to be started with \&.

.. option:: --auto-shutdown arg

   Enable\/disable self\-shutdown because a master module shutdown.
   This only works when messaging is enabled and the master
   module sends a shutdown message \(enabled with \-\-start\-stop\-msg
   for the master module\).

.. option:: --shutdown-master-module arg

   Set the name of the master\-module used for auto\-shutdown.
   This is the application name of the module actually
   started. If symlinks are used, then it is the name of
   the symlinked application.

.. option:: --shutdown-master-username arg

   Set the name of the master\-username of the messaging
   used for auto\-shutdown. If \"shutdown\-master\-module\" is
   given as well, this parameter is ignored.


Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
   4:debug.

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

.. option:: --component arg

   Limit the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging backend. The output usually goes to
   \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Execute in debug mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 .

.. option:: --log-file arg

   Use alternative log file.


Messaging
---------

.. option:: -u, --user arg

   Overrides configuration parameter :confval:`connection.username`.

.. option:: -H, --host arg

   Overrides configuration parameter :confval:`connection.server`.

.. option:: -t, --timeout arg

   Overrides configuration parameter :confval:`connection.timeout`.

.. option:: -g, --primary-group arg

   Overrides configuration parameter :confval:`connection.primaryGroup`.

.. option:: -S, --subscribe-group arg

   A group to subscribe to.
   This option can be given more than once.

.. option:: --content-type arg

   Overrides configuration parameter :confval:`connection.contentType`.

.. option:: --start-stop-msg arg

   Set sending of a start and a stop message.


SCIMEX
------

.. option:: --print-default-routingtable

   Print the default object routing table.