SeedLink was designed for real-time data transfer. A SeedLink client can only access data that is in a relatively short real-time ringbuffer. Moreover, SeedLink does neither have the functionality to query the station database nor deal with the instrument responses and thus does not support full SEED. ArcLink complements SeedLink by providing the above functionality. The ArcLink protocol is similar to SeedLink: it is based on TCP and uses simple commands in ASCII coding. One conceptual difference is that the client not “subscribes” to real-time streams, but requests data based on time windows. Unlike SeedLink, the data will not be sent immediately, but possibly minutes or even hours later, when the request is processed. An ArcLink request is associated with a request !ID that can be used by the client to get the status of the request, to download the data and to delete the request. The ArcLink server does not access the data archive directly, but delegates this job to a “request handler”. Thus, it is possible to use ArcLink for accessing different data archives by using different request handlers. This is equivalent to SeedLink that can get real-time data from different sources. The request handler is analogous to a SeedLink plug-in, however, while SeedLink starts exactly one instance of each defined plug-in at startup, ArcLink uses a single request handler and starts one instance of request handler per request. In addition to waveforms and metadata, it is also possible to request routing information from an ArcLink server. The routing information tell which ArcLink server provides the data of a given station. The routing database itself is supposed to be synchronized between all ArcLink servers. In this way a client can connect to any public ArcLink server, requests routing information and splits the request accordingly.
Status XML:
The status XML document is returned by the status command as described below. Some description of this XML document can be found here: http://www.seiscomp3.org/wiki/doc/applications/arclink-status-xml
Inventory XML:
Is the ArcLink Mapping of the Seiscomp3 iventory schemma.
Routing XML:
Is the ArcLink Mapping of the Seiscomp3 routing schemma.
The generic request format is the following:
REQUEST <request_type> <optional_attributes> <start_time>,<end_time>,<net>,<station>,<stream>,<loc_id>,<optional_constraints> [more request lines...] END
Allowed request types are currently WAVEFORM, RESPONSE, INVENTORY, ROUTING and QC. Data format of WAVEFORM and RESPONSE requests is SEED (Mini-SEED, dataless SEED, full SEED). Data format of INVENTORY, ROUTING and QC requests is XML. Data can be optionally compressed by bzip2.
If request_type==WAVEFORM, attributes “format” and “compression” are defined. The value of “format” can be “MSEED” for Mini-SEED or “FSEED” (default) for full SEED; “compression” can be “bzip2” or “none” (default). Wildcards are allowed only in stream and loc_id. Constraints are not allowed. loc_id is optional. If loc_id is missing or “.”, only streams with empty location ID are requested. Sample waveform request:
REQUEST WAVEFORM format=MSEED 2005,09,01,00,05,00 2005,09,01,00,10,00 IA PPI BHZ . END
If request_type==RESPONSE, attribute “compression” is defined, which can be “bzip2” or “none” (default). Constraints are not allowed. Wildcard “*” is allowed in station stream and loc_id, so it is possible to request a dataless volume of a whole network. If loc_id is missing or “.”, only streams with empty location ID are included in the dataless volume.
If request_type==INVENTORY, attributes “instruments”, “compression” and ”modified_after” are defined. The value of “instruments” can be “true” or ”false”, “compression” can be “bzip2” or “none” (default), and ”modified after”, if present, must contain an ISO time string. instruments [false] whether instrument data is added to XML compression [none] compress XML data modified after if set, only entries modified after given time will be returned. Can be used for DB synchronization. Wildcard “*” is allowed in all fields, except start time and end time. station, stream and loc_id are optional. If station or stream is not specified, the respective elements are not added to the XML tree; if loc_id is missing or “.”, only streams with empty location ID are included. For example, to request a just a list of GEOFON stations (but not stream information), one would use:
REQUEST INVENTORY 1990,1,1,0,0,0 2030,12,31,0,0,0 GE * END
The following constraints are defined:
If any of station, stream or loc id is missing, one or more dots should be used before constraints. For example, to request the list of networks with open data, one would use:
REQUEST INVENTORY 1990,1,1,0,0,0 2030,12,31,0,0,0 * . restricted=false END
If request_type==ROUTING, attributes “compression” and “modified_after” are defined. The value of “compression” can be “bzip2” or “none” (default); ”modified after”, if present, must contain an ISO time string. compression [none] compress XML data modified after if set, only entries modified after given time will be returned. Can be used for DB synchronization. Wildcard “*” is allowed in all fields, except start time and end time. Constraints are not allowed. All fields except start time, end time and net are optional; missing station stands for “default route” of a given network. stream and loc id are ignored.
If request_type==QC, attributes “compression”, ”outages”, ”logs” and ”parameters” are defined. The value of “compression” can be “bzip2” or “none” (default). compression [none] compress XML data outages include list of outages (“true” or “false”). logs include log messages (“true” or “false”). parameters comma-separated list of QC parameters. Wildcard “*” is allowed in all fields, except start time and end time. All fields must be present. Constraints are not allowed. The following QC parameters are implemented in the present version: availability, delay, gaps count, gaps interval, gaps length, latency, offset, overlaps count, overlaps interval, overlaps length, rms, spikes amplitude, spikes count, spikes interval, timing quality. These parameters are documented at doc/applications/scqc.
ArcLink commands consist of an ASCII string followed by zero or more arguments separated by spaces and terminated with carriage return (<cr>, ASCII code 13) followed by an optional line feed (<lf>, ASCII code 10). Except for STATUS, the response on the command consists of one or several lines terminated with <cr><lf>. Unless noted otherwise, the response is OK<cr><lf>or ERROR<cr><lf>, depending if the command has been successful or not. After getting the ERROR response, it is possible to retrieve the error message with SHOWERR. The following ArcLink commands are defined:
The ArcLink server sends a request to a request handler in the following format:
USER <username> <password> [INSTITUTION <any string>] [LABEL <label>] REQUEST <request_type> <req_id> <optional_attributes> [one or more request lines...] END
After receiving the request, the request handler can send responses to the server. The following responses are defined:
Status | Description |
OK | request successfully processed, data available |
NODATA | no processing errors, but data not available |
WARN | processing errors, some downloadable data available |
ERROR | processing errors, no downloadable data available |
RETRY | temporarily no data available |
DENIED | access to data denied for the user |
CANCEL | processing cancelled (eg., by operator) |
ArcLink server uses file descriptor 62 to send request to a request handler and reads status responses from file descriptor 63. It is possible to test a request handler interactively by running a command similar to following:
python reqhandler -vvv 62>&0 63<&1 >reqhandler.log 2>&1
Now the program “reqhandler” waits for input from terminal and writes output to terminal as well. Additionally a logfile is written.
Let's type the following request:
USER somebody@gfz-potsdam.de REQUEST WAVEFORM 123 format=MSEED 2008,2,21,2,50,0 2008,2,21,3,10,0 EE MTSE BHZ . 2008,2,21,2,50,0 2008,2,21,3,10,0 GE WLF BHZ . END
The log might look similar to following:
01 [None] > USER somebody@gfz-potsdam.de 02 [None] > REQUEST WAVEFORM 123 format=MSEED 03 [123] new WAVEFORM request from somebody@gfz-potsdam.de, None 04 [123] > 2008,2,21,2,50,0 2008,2,21,3,10,0 EE MTSE BHZ . 05 [123] < STATUS LINE 0 PROCESSING GFZ 06 [123] > 2008,2,21,2,50,0 2008,2,21,3,10,0 GE WLF BHZ . 07 [123] < STATUS LINE 0 SIZE 43008 08 [123] > END 09 [123] < STATUS LINE 1 PROCESSING GFZ 10 [123] < STATUS LINE 0 OK 11 [123] < STATUS LINE 1 MESSAGE size not known 12 [123] < STATUS LINE 1 OK 13 [123] < STATUS VOLUME GFZ SIZE 73728 14 [123] < STATUS VOLUME GFZ OK 15 [123] < END
Note that the status responses are asynchronous.
Minimal status response when data is available:
STATUS LINE 0 PROCESSING GFZ STATUS LINE 1 PROCESSING GFZ STATUS LINE 0 OK STATUS LINE 1 OK STATUS VOLUME GFZ SIZE 73728 STATUS VOLUME GFZ OK END
Minimal status response (and an optional error message) when data is not available:
STATUS LINE 0 PROCESSING GFZ STATUS LINE 1 PROCESSING GFZ STATUS LINE 0 NODATA STATUS LINE 1 NODATA STATUS VOLUME GFZ NODATA MESSAGE optional error message END
arclink.ini has the same syntax as seedlink.ini. It may contain several sections, but only one has the same name as the executable being used. A section in arclink.ini has the following structure (default values are shown in squared brackets, but relying on them is not recommended):