.. highlight:: rst

.. _capstool:

########
capstool
########

**CAPS command-line interface (CLI) client.**


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

capstool is a CAPS client application for retrieving data and listing available
streams from an operational CAPS server.

Applications
============

* Connectivity test to a CAPS server (:option:`-P`).
* Request of available streams (:option:`-Q`, :option:`-I`). The result set may
  vary depending on the client's IP address or the user name used for the
  connection.
* Data retrieval to stdout or individual files (:option:`-o`). Data may be
  requested in order of sampling time or time of arrival (:option:`--ooo`). It may
  also be retrieved downsampled to 1Hz (:option:`--heli`).
* Data quality control by listing gaps (:option:`-G`), continous data segments
  (:option:`-S`) or record arrival times (:option:`-M`).
* Data cleanup on the server side (:option:`--purge`).
* Retrieval of  server statistics (:option:`-X`).


Input
=====

The program reads requests from file or from standard input if no file is specified.
The request format is defined as follows:

.. code-block:: params

   YYYY,MM,DD,HH,MM,SS YYYY,MM,DD,HH,MM,SS Network Station [Location] Channel

Each request line contains a start and an end time followed by a stream id. The
fields Network, Station, Channel and Location support wild cards (*). The latter
one is optional. For matching all locations please use the '*' symbol, if empty
it assumes that only empty locations are being requested.

.. note::

   The request lines can be generated for a particular event using
   :cite:t:`scevtstreams` as of the SeisComP3 release Jakarta-2018.xxx.

Example:

.. code-block:: params

   2010,02,18,12,00,00 2010,02,18,12,10,00 GE WLF BH*
   2010,02,18,12,00,00 2010,02,18,12,10,00 GE VSU 00 BH*


Output
======

The output format differs by record type. Below is an overview of the available
formats.

.. csv-table::
   :header: "Record type", "Output data format"
   :widths: 1,1

   RAW, ASCII SLIST
   MSEED, MSEED
   ANY, Stored data format

.. note::

   When retrieving miniSEED data the records are not necessarily sorted by time.
   However, sorting by time is required, e.g., for processing in playbacks.
   Use :cite:t:`scmssort` for sorting the records by time. Example:

   .. code-block:: sh

      scmssort -E -u data.mseed > data_sorted.mseed


Examples
========

* **List available streams:**

  .. code-block:: sh

     capstool -H localhost:18002 -Q

* **Secured connection:**

  Connect via Secure Sockets Layer (SSL) and supply credentials for
  authentication.

  .. code-block:: sh

     capstool -H localhost:18002 -s -c user:password -Q

* **Time-based request without request file:**

  Request file to load miniSEED data for some GE stations:

  .. code-block:: params

     2010,02,18,12,00,00 2010,02,18,12,10,00 GE WLF BH*
     2010,02,18,12,00,00 2010,02,18,12,10,00 GE VSU BH*

  Submit the request in :file:`req.txt` to the CAPS server, and download miniSEED
  data to the file :file:`data.mseed`.

  .. code-block:: sh

     capstool -H localhost:18002 -o data.mseed req.txt

* **Time-based request without request file:**

  Request miniSEED data from a CAPS server. Provide request parameters from
  standard input. Write the miniSEED data to standard output. Re-direct the
  output and append it to a file, e.g., :file:`data.mseed`:

  .. code-block:: sh

     echo "2015,11,08,10,47,00 2015,11,08,11,00,00 * * BH?" |\
     capstool -H localhost:18002 >> data.mseed

* **Event-based request:**

  Request miniSEED data from a CAPS server for a particular event with ID <eventID>.
  Provide the request file using :cite:t:`scevtstreams`. Write the miniSEED data
  to standard output. Re-direct the output to a file, e.g., :file:`<eventID>.mseed`.

  .. code-block:: sh

     scevtstreams -d mysql://sysop:sysop@localhost/seiscomp -E <eventID> --caps > req.txt
     capstool -H localhost:18002 req.txt > <eventID>.mseed

* **Video data:**

  Request to load video data from Station HILO. Request file:

  .. code-block:: params

     2013,08,01,00,00,00 2013,08,01,00,30,00 VZ HILO WLS CAM
     2013,08,01,00,00,00 2013,08,01,00,30,00 VZ HILO WLS CAM

  Submit the request in :file:`req.txt` to the CAPS server, and download the video data
  to files using the given pattern:

  .. code-block:: sh

     capstool -H localhost:18002 -o "%H%M%S.%f" req.txt




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

:program:`capstool [options]`

.. _Options:


Options
-------

.. option:: -h, --help

   Show a help message and exit.

.. option:: -H, --host HOST[:PORT]

   Default: ``localhost:18002``

   Host and optionally port of the CAPS server \(default is localhost:18002\).

.. option:: -s, --ssl

   Use secure socket layer \(SSL\).

.. option:: -c, --credentials USER[:PASSWORD]

   Authentication credentials. If the password is omitted, it is asked for on command\-line.

.. option:: -P, --ping

   Retrieve server version information and exit.

.. option:: -Q

   Print availability extents of all data streams.

.. option:: -I, --info-streams FILTER

   Like \-Q but with a use a regular filter expression for the requested streams, e.g., AM.\*.

.. option:: --filter-list

   Identical to \-I.

.. option:: --mtime [start]:[end]

   Restrict request to record modification time window. Time format:
   %Y,%m,%d[,%H[,%M[,%S[,%f]]]]

.. option:: -X, --info-server

   Request server statistics in JSON format.

.. option:: --modified-after TIME

   Limit server statistics request to data modified after specific time. Time format:
   %Y,%m,%d[,%H[,%M[,%S[,%f]]]]

.. option:: --force

   Disable any confirmation prompts.


.. _Options (request file, no data download):


Options (request file, no data download)
----------------------------------------

.. option:: -G, --print-gaps

   Request list of data gaps.

.. option:: -S, --print-segments

   Request list of continuous data segments.

.. option:: --tolerance SECONDS

   Default: ``0``

   Threshold in seconds defining a data gap \(decimal point, microsecond precision\).

.. option:: -R, --Resolution DAYS

   Default: ``0``

   The resolution in multiple of days of the returned data segments or gaps. A value of 0 returns
   segments based on stored data records. A value larger than zero will return the minimum and
   maximum data time of one, two or more days. Consecutive segments will be merged if end and start
   time are within the tolerance.

.. option:: --print-stat

   Request storage information with a granularity of one day.

.. option:: --purge

   Deletes data from CAPS archive with a granularity of one
   day. Any data file intersecting with the time window
   will be purged. The user requires the purge permission.


.. _Options (request file and data download):


Options (request file and data download)
----------------------------------------

.. option:: -o, --output-file FILE

   Output file for received data \(default: \-\). The file name is used as a prefix with the
   extension added based on the record type \(MSEED, RAW, ANY, META, HELI\). Multiple files are
   created if mixed data types are received. For 'ANY' records the file name may contain the
   following format controls: %Y \- year, %j \- day of year, %H \- hour, %M \- minute, %S \- second, %F
   \- format.

.. option:: --any-date-format FORMAT

   Default: ``%Y%m%d_%H%M%S``

   Date format to use for any files, see 'man strftime'.

.. option:: -t, --temp-file FILE

   Use temporary file to store data. On success move to output\-file.

.. option:: --rt

   Enable real time mode.

.. option:: --ooo

   Request data in order of transmission time instead of sampling time.

.. option:: --out-of-order

   Identical to \-\-ooo.

.. option:: -D, --heli

   Request down\-sampled data \(1Hz\). The server will taper, bandpass filter and re\-sample the data.

.. option:: --itaper SECONDS

   Timespan in SECONDS for the one\-sided cosine taper.

.. option:: --bandpass RANGE

   Corner frequency RANGE of the bandpass filter, e.g., 1.0:4.0.

.. option:: -M, --meta

   Request record meta data only.

.. option:: -v, --version VERSION

   Request a specific format version. Currently only supported in meta requests.


