The ArcLink protocol is a plain ASCII protocol. On connection, the server waits for a sequence of commands from the client. Each command is processed sequentially and the client should waits for the previous command to end before sending a new command.
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 command.
The description of every know command to the ArcLink client protocol is given here.
To make a request to an ArcLink server the user should initially identify itself using the USER command. After this operation is performed and you received an OK string from the server you can start a request by using the REQUEST command. The REQUEST command is the only multiple lines command given to the ArcLink server, to end a REQUEST command you should use the END command.
The general representation of a request is:
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. Resulting data format of WAVEFORM and RESPONSE requests is SEED (Mini-SEED or full SEED for WAVEFORM and dataless SEED for RESPONSE). Data format of INVENTORY, ROUTING and QC requests is XML. Data can be optionally compressed by bzip2 when the optional_options contains the compression option set (e.g. compression=bzip2).
The start_time and end_time are strings containing: YYYY,MM,DD,HH,MM,SS e.g. "1980,1,1,0,1,1" and net is normally a FDSN network code, station a station code, stream a stream code and loc_id a location code.
The server does a check on the request type and after the REQUEST command it returns OK or ERROR. If ERROR is returned the request type was rejected by the server. If OK is received you should continue and supply to the server the request lines and finish the REQUEST block with an END command.
When no errors are found the server will attribute a request ID to your request, and as soon as a request handler of the correct type is free your request will be sent for processing. In the meatime your request status will be marked as UNSET status. At this point, the server also returns to the user the request ID attributed to this request that should be used for checking status, download and purging the request afterwards.
If request_type is 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 is 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. The dataless volume generated is compatible with the FDSN dataless seed specifications.
If request_type is INVENTORY, attributes "instruments", "compression" and "modified_after" are defined. The value of "instruments" can be "true" or "false" (default), "compression" can be "bzip2" or "none" (default), and "modified_after", if present, must contain an ISO time string. When instruments is set to true whether instrument data is added to XML, compression set bzip2 compress the XML data and modified_after if set, only entries modified after given time will be returned. 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 list of GEOFON stations (but not location and streams information), one would use:
REQUEST INVENTORY 1990,1,1,0,0,0 2030,12,31,0,0,0 GE * ENDFor inventory requet type the following constraints are defined:
- sensortype
- limit streams to those using specific sensor types: "VBB", "BB", "SM", "OBS", etc. Can be also a combination like "VBB+BB+SM".
- latmin
- minimum latitude
- latmax
- maximum latitude
- lonmin
- minimum longitude
- lonmax
- maximum longitude
- permanent
- true or false, requesting only permanent or temporary networks respectively
- restricted
- true or false, requesting only networks/stations/streams that have restricted or open data respectively.
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 ENDMore than one constrain can be added and should be separated by spaces.
If request_type is 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 set to bzip2 will compress XML data and modified after if set, only entries modified after given time will be returned. 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 is QC, attributes "compression", "outages", "logs" and "parameters" are defined. The value of "compression" can be "bzip2" or "none" (default). compression set to bzip2 will compress XML data, outages include list of outages ("true" or "false"). logs include log messages ("true" or "false"). parameters can contain a 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 [wiki:doc/applications/scqc].