You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
391 lines
12 KiB
Plaintext
391 lines
12 KiB
Plaintext
1 year ago
|
.. 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\)
|
||
|
|