.. highlight:: rst

.. _scbulletin:

##########
scbulletin
##########

**Create bulletins from SCML.**


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

scbulletin transforms the parameters of an event or an origin either to autoloc1
or to autoloc3 format.


Input Modes
-----------

Two modes of parameter input are possible:

1. Either one can fetch all necessary information from database directly
#. or one can provide a representation of the origin as XML file, to transform it
   to a standard format.

The first mode is the dump-mode the second is the input-mode. For dumping either
choose eventID or the originID. If the eventID is choosen the preferred origin
will be used.


Output Modes
------------

Different output formats are available by command-line options:

#. ``-1`` for **autoloc1**: Print one bulletin per event.
#. ``-3`` for **autoloc3**: Print one bulletin per event.
#. ``--fdsnws`` for FDSNWS event text: Print one line per event. Useful for
   generating event catalogs. This option offers an alternative to generating
   event catalogs by :ref:`fdsnws-event <sec-event>`.
#. ``-3 -x`` for **extended autoloc3**.
#. ``-1 -e`` or ``-3 -e`` for **enhanced** output at high-precision. All times
   and distances are in units of milliseconds and meters, respectively.

If called with an event or origin ID, a database connection is necessary to
fetch the corresponding object. Otherwise scbulletin will read the input source
(defaults to stdin), grab the found events or origins and dump the bulletins.
The input can be filtered by the event or origin IDs. Event and origin IDs can
be provided by :ref:`scevtls` and :ref:`scorgls`, respectively.


Examples
========

#. Create a bulletin from one or multiple event(s) in database

   .. code-block:: sh

      scbulletin -d mysql://sysop:sysop@localhost/seiscomp -E gfz2012abcd
      scbulletin -d mysql://sysop:sysop@localhost/seiscomp -E gfz2012abcd,gfz2022abcd

#. Convert XML file to bulletin

   .. code-block:: sh

      scbulletin < gfz2012abcd.xml

   .. code-block:: sh

      scbulletin -i gfz2012abcd.xml


#. Convert XML file to bulletin but filter by event ID(s)

   .. code-block:: sh

      scbulletin -i gfz2012abcd.xml -E gempa2022abcd
      scbulletin -i gfz2012abcd.xml -E gempa2022abcd,gfz2022abcd

.. note::

   When considering a single event XML file containing many events, the
   bulletins of all events will be generated unless ``--first-only`` is used.


.. _scbulletin_configuration:

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

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

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




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

.. program:: scbulletin

:program:`scbulletin [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.


Database
--------

.. option:: --db-driver-list

   List all supported database drivers.

.. option:: -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\".

.. option:: --config-module arg

   The config module to use.

.. option:: --inventory-db arg

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

.. option:: --db-disable

   Do not use the database at all


Input
-----

.. option:: -f, --format arg

   Input format to use \(xml [default], zxml \(zipped xml\), binary\).

.. option:: -i, --input arg

   The input file. Default is stdin.


Dump
----

.. option:: -E, --event arg

   ID of event that is read from database and transformed into
   a bulletin. Separate multiple IDs by comma.\"

.. option:: -O, --origin arg

   ID of origin that is read from database and transformed into
   a bulletin. Separate multiple IDs by comma.

.. option:: -1, --autoloc1

   Use autoloc1 format for output. This is default.

.. option:: -3, --autoloc3

   Use autoloc3 format for output.

.. option:: -x, --extra

   Use a specially detailed autoloc3 format. This options works
   only in combination with the autoloc3\-flag.

.. option:: -e, --enhanced

   Enhanced output with higher precision. Times: milliseconds,
   distances: meter. Use for bulletins of local earthquakes.

.. option:: --event-agency-id

   Use the agency ID of the event instead of the preferred origin.

.. option:: --fdsnws

   Dump in FDSNWS event text format, e.g., for generating catalogs.

.. option:: --first-only

   Convert only the first event\/origin to bulletin. Otherwise
   all events or origins will be converted to single bulletins
   which will be concatenated.

.. option:: -k, --dist-in-km

   Plot distances in km instead of degree.

.. option:: -p, --polarities

   Dump onset polarities.

.. option:: -w, --weight arg

   Weight threshold for printed and counted picks.

.. option:: -x, --extra

   Use a specially detailed autoloc3 format. This options works only
   in combination with the autoloc3\-flag.