.. highlight:: rst

.. _scimex:

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

**SeisComP3 event exchange between two systems.**


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

scimex manages the SC3 object exchange between different SeisComP3 systems in
realtime. scimex may import or export the data to one or several systems. In
contrary to :ref:`scimport` the exchange of the SC3 objects is event based.

By default all objects (picks, amplitudes, origins, arrivals, station magnitudes,
magnitudes, magnitude references) are transferred to the other system. The user
can define filters to exclude objects from being transferred. Possible filter
parameter are 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 scmasters 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 system an instance of scimex is running in import mode. It
fetches the whole event information from the IMPORT group, checks the local
filter criteria of the system and sends the collected objects to the different
messages 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
========

scimex_import.cfg

.. code-block:: sh

   connection.username = scimexIm
   connection.server = localhost

   mode = IMPORT

   cleanUpInterval=86400

   importSink = 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


scimex_export.cfg

.. code-block:: sh

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

   mode = EXPORT

   cleanUpInterval = 7200
   exportSink = 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



Configuration
=============

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

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



.. confval:: mode

   Type: *string*

   Type of mode, options are IMPORT or EXPORT.


.. confval:: cleanupinterval

   Type: *double*

   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
   SeisComP3 datamodel version 0.51 \(imexscdm0.51\)
   is supported which was used in release Barcelona \(2008\).


.. confval:: importHosts

   Type: *string*

   List of importing systems \(AgencyIDs\) defined like recipients.


.. confval:: exportHosts

   Type: *string*

   List of recipients names \(AgencyIDs\) defined in the following,
   e.g. EMSC, IGN.


.. 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*

   Tuple of doubles that defines the latitude range, e.g. \-90:90.


.. confval:: criteria.\$name.longitude

   Type: *tuple:double*

   Tuple of doubles that defines the longitude range, e.g. \-180:180.


.. confval:: criteria.\$name.magnitude

   Type: *tuple:double*

   Tuple of doubles that defines the magnitude range, e.g. 3:10.


.. confval:: criteria.\$name.arrivalcount

   Type: *int*

   Number of minimum arrivals.


.. confval:: criteria.\$name.agencyid

   Type: *list:string*

   White lits of agency ids.


.. 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 sink, e.g. address \= 192.168.1.1.


.. 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.\*.


.. confval:: hosts.\$name.filter

   Type: *boolean*

   Enables\/disables filtering based on defined criteria. If set to
   false and even a criteria is defined, all events will pass.
   Default is ``true``.

.. confval:: hosts.\$name.conversion

   Type: *string*

   Optional target format for export.


.. confval:: hosts.\$name.useDefinedRoutingTable

   Type: *boolean*

   Enables\/disables defined routing tables.
   Default is ``false``.

.. confval:: hosts.\$name.routingTable

   Type: *list:string*

   Defining routing tables in the meaning of mapping objects to message
   groups. E.g. Pick:NULL, StationAmplitude:NULL, Origin:LOCATION,
   StationMagnitude: MAGNITUDE, NetworkMagnitude:MAGNITUDE,
   MagnitudeReference:MAGNITUDE, OriginReference:EVENT, Event:EVENT.



Command-line
============

.. program:: scimex


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, eg 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

   Sets 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

   Sets 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

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

.. option:: -s, --syslog

   Use syslog logging back end. 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

   Debug mode: \-\-verbosity\=4 \-\-console

.. 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:: --encoding arg

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

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

   Sets sending of a start\- and a stop message.


IMEX
----

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

   Print the default object routingtable.