SCDISPATCH(1)

NAME
scdispatch - SeisComP Documentation

Read objects (event, origin, etc) from a SCML file and sends the objects to the messaging system.

DESCRIPTION

scdispatch reads an SCML file and creates notifier objects for them that are sent to the messaging and the corresponding messaging groups (see --routingtable). In contrast to scdb which writes SCML files directly into the database scdispatch uses the messaging bus. If scmaster is configured with the database plugin, messages will end up in the database as well.

  Modes

scdispatch can work in two modes applying different operations:

•   Without database check: One of the operations add, update or remove is selected along with the option -O. In that case all objects in the SCML are encapsulated in a notifier with that specific operation and sent to the messaging. No check is performed if the object is already in the database or not.

•   With database check: The option -O is not given or the option is used along with one of the operations merge or merge-without-remove. scdispatch first tries to load the corresponding objects from the database and calculates differences. It will then create the corresponding notifiers with operations add, update or remove and sends them to the messaging. That mode is quite close to a sync operation with the exception that top level objects (such as origin or event) that are not part of the input SCML are left untouched in the database. It can be used to synchronize event information from one system with another.

  Operations

Different operations can be chosen along with the option -O. If -O is not given, merge is assumed by default.

•   Add: All objects are sent trying to be added to the database. If they already exist in the database, they will be rejected and not spread through the messaging. Modules connected to the messaging will not receive rejected objects.

•   Remove: All sent objects with all their attributes and child objects are removed from the database. Modules connected to the messaging will not receive any sent object.

•   Update: All objects are sent trying to be updated to the database along with all of their child objects and attributes. Sent objects not existing in the database will be ignored and not received by any module connected to the messaging. Child objects and attributes existing in the database but not included in the sent object will be removed as well.

•   Merge (default): Applies Add and Update and requires a database connection.

•   Merge-without-remove: Applies Add and Update and requires a database connection. However, no objects are removed from the database.

    NOTE: All SeisComP objects along are listed and described along with their child objects and attributes in the API documentation.

  Examples

1.  Send different objects from a SCML file for merging (adding or updating). The option -O can be ommitted because the default behavior is to merge:

    scdispatch -i test.xml -O merge
    scdispatch -i test.xml

2.  Send all objects by ignoring events. When scevent receives origins it will create new events or associate the origins to existing ones. The ignored events may be already existing with different IDs. Hence, event duplication is avoided by ignoring them.

    scdispatch -i test.xml -e

3.  Send new objects to be added:

    scdispatch -i test.xml -O add

4.  Send an update of objects:

    scdispatch -i test.xml -O update

5.  Send objects to be removed:

    scdispatch -i test.xml -O remove

6.  Compare new objects with the database content and send the difference (optionally without removing objects):

    scdispatch -i test.xml -O merge
    scdispatch -i test.xml -O merge-without-remove

7.  Offline mode: all operations can be performed without the messaging system using xml files:

    scdispatch -i test.xml -O operation --create-notifier > notifier.xml

    then:

    scdb -i notifier.xml

8.  Subsets of SCML Objects

    It can be useful to import a subset of QuakeML objects, e.g. Origins from other agencies and then allow scevent to associate them to existing events (and possibly prefer them based on the rules in scevent) or create new events for the origins. If the event objects from a SCML file are not required to be sent to the messaging then either they should be removed (e.g. using XSLT) and all the remaining objects in the file added:

    scdispatch -i test.xml -O add

    or the event objects can be left out of the routing table, e.g.

    scdispatch -i test.xml -O add \
               --routingtable Pick:PICK, \
                              Amplitude:AMPLITUDE, \
                              Origin:LOCATION,StationMagnitude:MAGNITUDE, \
                              Magnitude:MAGNITUDE

    HINT: The option --no-event is a wrapper for removing Event:EVENT from the routing table. With this option no event objects will be sent which may be useful if just the origins with magnitudes, amplitudes, arrivals, picks, etc. shall be integrated, e.g. after XML-based playbacks.

9.  Testing

    For testing it is useful to watch the results of dispatch with scolv or scxmldump. It is also useful to clean the database and logs to remove objects from persistent storage to allow repeated reloading of a file.

    NOTE: The following will clear all events from the database and any other other object persistence. Modify the mysql command to suit your db setup.

    mysql -u root --password='my$q1' -e "DROP DATABASE IF EXISTS seiscomp; \
      CREATE DATABASE seiscomp CHARACTER SET utf8 COLLATE utf8_bin; \
      GRANT ALL ON seiscomp.* TO 'sysop'@'localhost' IDENTIFIED BY 'sysop'; \
      USE seiscomp;source seiscomp/trunk/share/db/mysql.sql;"
    seiscomp start

MODULE CONFIGURATION
etc/defaults/global.cfg
etc/defaults/scdispatch.cfg
etc/global.cfg
etc/scdispatch.cfg
~/.seiscomp/global.cfg
~/.seiscomp/scdispatch.cfg

scdispatch inherits global options.

COMMAND-LINE OPTIONS

scdispatch [options]

  Generic

-h, --help
    Show help message.

-V, --version
    Show version information.

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

--plugins arg
    Load given plugins.

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

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

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

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

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

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

-q, --quiet
    Quiet mode: no logging output.

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

-s, --syslog
    Use syslog logging backend. The output usually goes to /var/lib/messages.

-l, --lockfile arg
    Path to lock file.

--console arg
    Send log output to stdout.

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

--log-file arg
    Use alternative log file.

  Messaging

-u, --user arg
    Overrides configuration parameter connection.username.

-H, --host arg
    Overrides configuration parameter connection.server.

-t, --timeout arg
    Overrides configuration parameter connection.timeout.

-g, --primary-group arg
    Overrides configuration parameter connection.primaryGroup.

-S, --subscribe-group arg
    A group to subscribe to. This option can be given more than once.

--content-type arg
    Overrides configuration parameter connection.contentType.

    Default: binary

--start-stop-msg arg
    Default: 0

    Set sending of a start and a stop message.

  Database

--db-driver-list
    List all supported database drivers.

-d, --database arg
    The database connection string, format: service://user:pwd@host/database. "service" is the name of the database driver which can be queried with "--db-driver-list".

--config-module arg
    The config module to use.

--inventory-db arg
    Load the inventory from the given database or file, format: [service://]location .

--db-disable
    Do not use the database at all

  Dispatch

-e, --no-events
    Do not send any event object which are ignored when reading event parameters.

-i, --input arg
    File from which the content is dispatched to the messaging.

-O, --operation arg
    Default: merge

    Values: add,update,remove,merge,merge-without-remove

    Merge and merge-without-remove require a database connection. Both will read the object corresponding to the sent object from the database and calculate the differences. Merge-without-remove behaves like merge with the exception that remove operations will be filtered out and no objects in the database will be removed.

    If add, update or remove is specified, then all objects in XML are sent with the given operation regardless of their existence in the database.

--print-objects
    Print names of routable objects.

--print-routingtable
    Print routing table.

--routingtable arg
    Default: Amplitude:AMPLITUDE,Event:EVENT,FocalMechanism:FOCMECH,Magnitude:MAGNITUDE, Origin:LOCATION,Pick:PICK,StationMagnitude:MAGNITUDE

    Specify routing table as comma separated list of object:group pairs, e.g. "Origin:LOCATION,Event:EVENT". When an object should be routed to a group and no table entry for that particular class type is available, all parent objects are checked for valid routing entries and the first found is used. E.g. if only "Origin:LOCATION" is specified but the input file contains also Arrivals which are child objects of Origin then the routing entry of Origin is used because of the parent-child relationship between Origin and Arrival.

--test
    Test mode. Does not send any object.

--create-notifier
    Do not send any object. All notifiers will be written to standard output in XML format.

AUTHOR
gempa GmbH, GFZ Potsdam

COPYRIGHT
gempa GmbH, GFZ Potsdam