.. highlight:: rst

.. _slinktool:

#########
slinktool
#########

**SeedLink query interface module**


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

slinktool connects to a :ref:`seedlink` server and queries the server for information
or requests data using uni-station or multi-station mode and prints information
about the packets received. All received packets can optionally be dumped to a
single file or saved in custom directory and file layouts.


Examples
========


All-station/Uni-station mode
----------------------------

The following would connect to a SeedLink server at slink.host.com port 18000 and
configure the link in all-station/uni-station mode, exactly which data are received
depends on the data being served by the SeedLink server on that particular port.
Additionally, all of the received packets are appended to the file 'data.mseed'
and each packet received is reported on the standard output. ::

   slinktool -v -o data.mseed slink.host.com:18000

The '-s' argument could be used to indicate selectors to limit the type of packets
sent by the SeedLink server (without selectors all packet types are sent). The
following would limit this connection to BHZ channel waveform data with a location
code of 10 (see an explanation of SeedLink selectors below). Additionally another
verbose flag is given, causing slinktool to report detailed header information
from data records. ::

   slinktool -vv -s 10BHZ.D -o data.mseed slink.host.com:18000


Multi-station mode
------------------

The following example would connect to a SeedLink server on localhost port 18010
and configure the link in multi-station mode. Each station specified with the '-S'
argument will be requested, optionally specifying selectors for each station. ::

   slinktool -v -S GE\_WLF,MN\_AQU:00???,IU\_KONO:BHZ.D :18010

This would request all data from the GEOFON station WLF as no selectors were indicated,
MedNet station AQU with location code 00 and all streams and waveform data from the
IU network station KONO from stream BHZ.
A variety of different data selections can be made simultaneously.

Examples:

* Horizontal BH channels, data only: ::

     -s 'BHE.D BHN.D' -S 'GE\_STU,GE\_MALT,GE\_WLF'

* Vertical channels only: ::

     -s BHZ -S GE\_STU,GE\_WLF,GE\_RUE,GE\_EIL


Wildcarding network and station codes
-------------------------------------

Some SeedLink implementations support wildcarding of the network and station codes.
If this is the case, the only two wildcard characters recognized are '\*' for
one or more characters and '?' for any single character.

As an example, all US network data can be requested using the following syntax ::

   -S 'US\_\*'


Seedlink Selectors
==================

SeedLink selectors are used to request specific types of data within a given data
stream, in effect limiting the default action of sending all data types.
A data packet is sent to the client if it matches any positive selector
(without leading "!") and doesn't match any negative selectors (with a leading "!").
The general format of selectors is LLSSS.T, where LL is location, SSS is channel
and T is type (one of [DECOTL] for Data, Event, Calibration, Blockette, Timing,
and Log records). "LL", ".T", and "LLSSS." can be omitted, implying anything in
that field. It is also possible to use "?" in place of L and S as a single character
wildcard. Multiple selectors are separated by space(s).

Examples: ::

   BH?          - BHZ, BHN, BHE (all record types)
   00BH?.D      - BHZ, BHN, BHE with location code '00' (data records)
   BH? !E       - BHZ, BHN, BHE (excluding detection records)
   BH? E        - BHZ, BHN, BHE & detection records of all channels
   !LCQ !LEP    - exclude LCQ and LEP channels
   !L !T        - exclude log and timing records


Archiving Data
==============

Using the '-A format' option received data can be saved in a custom directory and
file structure. The archive format argument is expanded for each packet processed
using the following flags: ::

   n : network code, white space removed
   s : station code, white space removed
   l : location code, white space removed
   c : channel code, white space removed
   Y : year, 4 digits
   y : year, 2 digits zero padded
   j : day of year, 3 digits zero padded
   H : hour, 2 digits zero padded
   M : minute, 2 digits zero padded
   S : second, 2 digits zero padded
   F : fractional seconds, 4 digits zero padded
   % : the percent (%) character
   # : the number (#) character
   t : single character type code:
         D - waveform data packet
         E - detection packet
         C - calibration packet
         T - timing packet
         L - log packet
         O - opaque data packet
         U - unknown/general packet
         I - INFO packet
         ? - unidentifiable packet

The flags are prefaced with either the % or # modifier. The % modifier indicates
a defining flag while the # indicates a non-defining flag. All received packets
with the same set of defining flags will be saved to the same file. Non-defining
flags will be expanded using the values in the first packet received for the
resulting file name.

Time flags are based on the start time of the given packet.

For example, the format string: ::

   /archive/%n/%s/%n.%s.%l.%c.%Y.%j

would be expanded to day length files named something like: ::

   /archive/NL/HGN/NL.HGN..BHE.2003.055

Using non-defining flags the format string: ::

   /data/%n.%s.%Y.%j.%H:#M:#S.miniseed

would be expanded to: ::

   /data/NL.HGN.2003.044.14:17:54.miniseed

resulting in hour length files because the minute and second are specified with the non-defining modifier. The minute and second fields are from the first packet in the file.


Stream List File
=================

The stream list file used with the '-l' option is expected to define a data stream
on each line. The format of each line is: ::

   Network Station [selectors]

The selectors are optional. If default selectors are also specified (with the '-s' option),
they they will be used when no selectors are specified for a given stream.

Example: ::

   ----  Begin example file -----
   # Comment lines begin with a '#' or '\*'
   # Example stream list file for use with the -l argument of slclient or
   # with the sl\_read\_streamlist() libslink function.
   GE ISP  BH?.D
   NL HGN
   MN AQU  BH? HH?
   ----  End example file -----


.. note::

   All diagnostic output from slinktool is printed to standard error (stderr).
   Exceptions are when

   * Printing miniSEED packet details with the *-p* option.
   * Printing unpacked samples with the *-u* option.
   * Printing the raw or formatted responses to INFO requests.


Author of slinktool
===================

Chad Trabant

ORFEUS Data Center/EC-Project MEREDIAN

IRIS Data Management Center

Original source code: https://github.com/iris-edu/slinktool/tree/master/doc



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

.. program:: slinktool

:program:`slinktool [OPTION]... [host][:][port]`

Address \([host][:][port]\) is a required argument. It specifies the address
of the SeedLink server in host:port format. Either the host, port or both
can be omitted. If host is omitted then localhost is assumed,
i.e. ':18000' implies 'localhost:18000'. If the port is omitted,
then 18000 is assumed, i.e. 'localhost' implies 'localhost:18000'.
If only ':' is specified, 'localhost:18000' is assumed.


General program options
-----------------------

.. option:: -V

   Print program version and exit.

.. option:: -h

   Print program usage and exit.

.. option:: -v

   Be more verbose. This flag can be used multiple times \(\"\-v \-v\" or \"\-vv\"\)
   for more verbosity. One flag: report basic handshaking \(link configuration\) details and
   briefly report each packet received. Two flags: report the details of the handshaking,
   each packet received and detailed connection diagnostics.

.. option:: -P

   Ping the server, report the server ID and exit.

.. option:: -p

   Print details of received Mini\-SEED data records. This flag can be used multiple times
   \(\"\-p \-p\" or \"\-pp\"\) for more detail. One flag: a single summary line
   for each data packet received. Two flags: details of the Mini\-SEED data records received,
   including information from fixed header and 100\/1000\/1001 blockettes.

.. option:: -u

   Print unpacked samples of data packets.

.. option:: -nd delay

   The network reconnect delay for the connection to the SeedLink server.
   If the connection breaks for any reason this will govern how soon a reconnection should
   be attempted.

.. option:: -nt timeout

   The network timeout \(in seconds\) for the connection to the SeedLink server. If no data
   [or keep alive packets?] are received in this time range the connection is closed and
   re\-established \(after the reconnect delay has expired\). The default value is 600 seconds.
   A value of 0 disables the timeout.

.. option:: -k interval

   Interval at which keepalive \(heartbeat\) packets are sent to the server.
   Keepalive packets are only sent if nothing is received within the interval.

.. option:: -x sfile[:interval]

   Save\/restore stream state information to this file.
   
   During client shutdown the last received sequence numbers and time stamps \(start times\)
   for each data stream will be saved in this file. If this file exists upon startup the information
   will be used to resume the data streams from the point at which they were stopped. In this way the
   client can be stopped and started without data loss, assuming the data are still available on the
   server. If an interval is specified the state will be saved every interval in that packets are
   received. Otherwise the state will be saved only on normal program termination.

.. option:: -d

   Configure the connection in \"dial\-up\" mode. The remote server will close the connection when
   it has sent all of the data in its buffers for the selected data streams. This is opposed to
   the normal behavior of waiting indefinitely for data.

.. option:: -b

   Configure the connection in \"batch\" mode.


Data stream selection
---------------------

.. option:: -s selector

   Selectors for uni\-station or default for multi\-station mode

.. option:: -l listfile

   Read a stream list from this file for multi\-station mode

.. option:: -S streams

   Define a stream list for multi\-station mode.
   
   'streams' \= 'stream1[:selectors1],stream2[:selectors2],...'
   
   'stream' is in NET_STA format, for example:
   
   \-S \"IU_KONO:BHE BHN,GE_WLF,MN_AQU:HH?.D\"

.. option:: -tw begin:[end]

   Specify a time window in year,month,day,hour,min,sec format.
   
   Example: \-tw 2002,08,05,14,00,00:2002,08,05,14,15,00
   
   The end time is optional, but the colon must be present.


Data saving options
-------------------

.. option:: -o dumpfile

   Write all received records to this file

.. option:: -A format

   If specified, all received packets \(Mini\-SEED records\) will be appended to a directory\/file
   structure defined by format. All directories implied in the format string will be created if
   necessary.

.. option:: -SDS SDSdir

   If specified, all received packets \(Mini\-SEED records\) will be saved into a Simple Data
   Structure \(SDS\) dir\/file structure starting at the specified directory. This directory and
   all subdirectories will be created if necessary. This option is a preset of the '\-A' option.
   The SDS dir\/file structure is:
   
   <SDSdir>\/<YEAR>\/<NET>\/<STA>\/<CHAN.TYPE>\/NET.STA.LOC.CHAN.TYPE.YEAR.DAY

.. option:: -BUD BUDdir

   If specified, all received waveform data packets \(Mini\-SEED data records\) will be saved into
   a Buffer of Uniform Data \(BUD\) dir\/file structure starting at the specified directory.
   This directory and all subdirectories will be created if necessary. This option is a preset
   of the '\-A' option. The BUD dir\/file structure is:
   
   <BUDdir>\/<NET>\/<STA>\/STA.NET.LOC.CHAN.YEAR.DAY


Data server
-----------

.. option:: -i type

   Send info request, type is one of the following:
   
   ID, CAPABILITIES, STATIONS, STREAMS, GAPS, CONNECTIONS, ALL
   
   The returned raw XML is displayed when using this option.

.. option:: -I

   Print formatted server id and version

.. option:: -L

   Print formatted station list \(if supported by server\)

.. option:: -Q

   Print formatted stream list \(if supported by server\)

.. option:: -G

   Print formatted gap list \(if supported by server\)

.. option:: -C

   Print formatted connection list \(if supported by server\)

