Seiscomp3 Development

The response from ArcLink to a status command, if no errors are found, is an XML file describing the status of the requests placed by a certain user to the server (the requests are not limited to the actual connection, but should spam all the requests made and not deleted). At the moment we don't have an exactly description of this document, but we keep this page update to the last version as returned by the ArcLink server.

This page refers to the old SeisComP 3 version, and may no longer be accurate. See seiscomp.de for the latest version.

Running thru a request

The basic concept of ArcLink is:

You connect
You identify yourself
You make 1 or more requests
1. Each request can have a label
2. Each can have a different type
Each request will be assigned a number (like a tracking number from DHL/UPS)
1. ^aWith this number you can get the status of your request
When your request is ready you can download your request (by volumes^b or the entire request) using the DOWNLOAD or BDOWNLOAD command.
After downloading it, you should purge your request using the PURGE command.

^a This is where this document can help you with. Here we are describing how interpret the information returned by the ArcLink status XML file.

^b A volume is a important concept of the ArcLink system. In a simple request a user can ask data from different stations, from different time periods. When the request is received by the ArcLink server (or ArcLink proxy server) it can be splited for optimizing the preparation of the data for downloading. Each group of data is called a Volume that would correspond to a certain number of lines of the original request.

One first example

Requesting the status of a request can be done using the command STATUS on a ArcLink server. You can request the status of a individual request by appeding to the command the request Id (the request Id is the number returned by the ArcLink server when you send the END command om a REQUEST block) or, you can request the status of all requests that you placed by appending the option ALL to the STATUS command.

For example, the folowing section of ArcLink communication:

hello
user mbianchi@somedomain.com
STATUS 1

would return the following XML file if the request Id number 1 is still on the server:

<?xml version="1.0"?>
<arclink>
  <request id="1" type="WAVEFORM" label="" args="format=MSEED" encrypted="true" size="204312" ready="true" error="false" message="">
    <volume id="BIA" dcid="GFZ" status="OK" size="204312" encrypted="true" message="">
      <line content="2010,1,1,10,0,0 2010,1,1,11,0,0 GE APE BHZ" status="OK" size="91648" message=""/>
      <line content="2010,1,1,10,0,0 2010,1,1,11,0,0 GE BKB BHZ" status="OK" size="112640" message=""/>
    </volume>
  </request>
</arclink>

This document has always a structure like this:

 arclink -> request -> volume -> line
 [1]        [1 > oo]   [1 > oo]  [1 > oo] <--- Indicates the possible repetition

Where there is only one arclink node, and could be many request nodes (when the option ALL is used on the STATUS command). The number of volumes and lines are also depending on the request sent.

The arclink node

The arclink node has no parameters. It only can contains request child nodes.

The request node

Each request node gives you information about a specific request, represented by a specific Id. The parameters for this node are:

id: Is the id that the arclink request received. This id is the answer of the ArcLink server to a successfully REQUEST command and should be used with the STATUS, DOWNLOAD, PURGE commands.

type: Gives information on the type of the request can be one of: WAVEFORM, INVENTORY, ROUTING, RESPONSE, QC, GREENSFUNC.

label: This is the label given to the request. This should be supplied by the user during submission of the request by the LABEL command before the REQUEST command.

args: Those, can be more than one, are the arguments passed to the arclink server during the command REQUEST and differ according to the type of the request.

encrypted: This flag indicates that the request will be delivered encrypted. If this flag is True you will received an encrypted file. For decrypting it read about the Arclink Encryption.

size: This is the total request size (in bytes) to be downloaded.

ready: This flag can be true/false indicating that the request is ready for download.

error: This flag indicates that an error has occurred during the processing of the request. More information should be available on the message parameter.

message: This parameters is a human-readable string describing the error occurred during processing of the request.

And, it can have only volumes as child nodes.

The volume node

In the sequence of the request there is a volume node. Your original request is spitted into volumes every time that the ArcLink server/proxy or even the Request Handler (that is part of the ArcLink) needs to. Normally, lines from one request that routes to a different node would be packed in different volumes, and also lines that are denied (by insufficient user permissions) are separated in different volumes for easing the debugging.

The parameters to the volume node are:

id: The Id for the specific Volume.

dcid: The datacenter Id that created that specific volume. On proxy servers each volume can come from a different ArcLink node (because of routing) and you could track down the datacenter of origin from a specific volume from this variable.

status: is a fixed string representing the status of the request. depending on the status further information (in a human readable form) should be available thru the message parameter. The possible values of the status parameters are defined by the ArcLink status interface. As a general interface the values of this parameters could be any of those:

UNSET: The element represented has no valid status defined.
PROCESSING: The element is on processing, data is on preparation and will be delivered soon.
CANCELLED: The element was cancelled and will not be ready. See more information on the message parameter.
OK: The element has finished and there was no errors. The result is ready for pick up.
WARNING: Some errors occurred during the processing of the element that didn't stop it from being prepared. See more information on the message parameter.
ERROR:: There were errors during the preparation of the element and no final result was prepared. See more information on the message parameter.
DENIED: You don't have the permission for the data involved in this element. See more information on the message parameter.
RETRY: Indicates that temporarily there are no data available.
NODATA: No data could be found for the element. The element is ready (i.e. nothing more left to process).

size: Is the size in bytes of the volume.

encrypted: This flag like in the request, indicate that this specific volume is encrypted and you would get an encrypted file if you download it.

message: Contains any additional messages related to the processing of this specific volume.

Finally, a volume can only contains line nodes as child nodes.

The line node

The last element of the status XML document is the line node. This element gives information about a specific time windows. Please keep in mind that the line elements of a processed request could not be the same as the ones in the requested message. Because of the characters expansion, a request message with BH? could be translated in to three different lines of request by programs like the arclink_fetch.

The line node, has the following elements:

content: This contains a copy of the request line (sometimes expanded).

status: This is also an ArcLink status interface message, and it can assume the values described above.

size: This is the total line size (in bytes) to be downloaded.