NetDC User Manual
Jump to:
NAME
NetDC - Networked Data Center Protocol
DESCRIPTION
NetDC is a data request system that allows a user to request seismological
information from multiple data centers through a single email
form. Information is delivered to the user through email and FTP
in a uniform digital or text format.
REQUEST FORMAT
A NetDC request has a similar layout to the familiar BREQ_FAST
request format, which has already been in use at various data centers
for several years.
Below is the general layout of the NetDC request. Some of the
fields are mandatory (bold red text). Note that fields may be separated
by spaces, tabs, or both (collectively refered to as white-space).
.NETDC_REQUEST |
.NAME <name of user requesting
data> |
.INST <name of institution> |
.MAIL <return mailing
address> |
.EMAIL <return email address>
|
.PHONE <phone number>
|
.FAX <fax number> |
.LABEL <user-assigned label
for request> |
.MEDIA <primary media selection>
|
.ALTERNATE MEDIA <alternate media
selection> |
.FORMAT_WAVEFORM <what format
to receive waveform traces in> |
.FORMAT_RESPONSE <what format
to receive response information in> |
.MERGE_DATA <YES or NO and waiting
time> |
.DISPOSITION <instructions
for FTP data transfer to user> |
.END |
<data request line #1> |
<data request line #2> |
<data request line #3> |
|
<data request line #N> |
Format Explained
.NETDC_REQUEST (mandatory) is a tag that identifies the
mail document as a request intended for NetDC. This must always
be the first line of the request.
.NAME (mandatory) indicates the name of the
user. This is needed to identify the request and allows for the
grouping of multiple requests by the same user.
.INST (mandatory) lists the institution that the
user belongs to. This can be a company name, educational institution
or any organization. This assists in establishing contact with
the user should it be necessary for servicing the request.
.MAIL indicates the postal address of the institution,
should it be necessary to send physical media containing the requested
information.
.EMAIL (mandatory) is the email address of the
requesting user. This entry is mandatory since the majority of
user contact will be through email.
.PHONE lists the users contact phone number.
.FAX indicates the fax machine number that the user has
access to.
.LABEL is a user-assigned label for the request, which
will appear in data files shipped to the user. If a label is not
specified, a default value will be assigned.
.MEDIA specifies the preferred media of delivery of the
data. Normally the media type will be predetermined by the type
and size of the data being shipped. Options are currently FTP,
EMAIL, EXABYTE TAPE, DAT TAPE, DLT TAPE, and possibly others.
.ALTERNATE MEDIA specifies a backup media option should
the first not be available.
.FORMAT_WAVEFORM indicates the format for the waveform
data to be shipped. Currently, the only option is "SEED".
SEED will also be the default format if this line is not provided.
.FORMAT_WAVEFORM SEED
.FORMAT_RESPONSE indicates the format for response
information when it is requested. The current default is "SEED
ASCII", which is a specific text output format for displaying
response data known as "RESP" format.
.FORMAT_RESPONSE SEED_ASCII
.MERGE_DATA requires a YES or NO entry, specifying
whether the data products should be combined at the hub data center
(i.e. the data center to which the original data request was sent)
before shipment to the user or if each data center should send
their shipment to the user individually. In the case of a YES
entry, a number of days should be entered which equates to the
wait time in days. After that point, the hub data center
will ship what it is able to provide and any late shipments will
be redirected to the user. Here is an example of how the user
would specify product merging with a two-day time window.
.MERGE_DATA YES 2
.DISPOSITION is an optional field for specifying how
to transfer data through FTP to the user. It will be followed
by one of two directives: PUSH or PULL. The PUSH
case directs the data center performing the shipment to open an
FTP dialogue with the user's host machine and put the data on
the user's machine. The PUSH directive is followed by the
host name and the anonymous FTP directory into which the data
is placed.:
.DISPOSITION PUSH myhost.seismology.edu /pub/dropoff
The PULL directive specifies that the user will get
the data through FTP manually once notified by email that it is
available. There is no need to specify a host name or directory
here:
.DISPOSITION PULL
.END (mandatory)is the entry that signals the
end of the request header. What follows the .END tag is one to
many data request lines, which list specifically what data
the user wants to receive. There is no set limit to the number
of data request lines a user can enter, but each line must be
a separate record with white space separators for each of the
fields.
Request Lines
The data request lines come in three flavors: .DATA,
.RESP, and .INV. .DATA lines request waveform
data, .RESP lines ask for response information,
and .INV queries a site for an inventory of data
holdings. All of these request types follow the same general format,
even though the response to each will differ.
Each request line is a separate entity
consisting of white-space separated fields. Each field in the
request line is a text string where the first field contains a
leading period. UNIX-style wildcards ? and
* can be used in many of the field strings,
which indicate "match to any one character" and "any
number of characters", respectively. The field layout of a
data request line is as follows:
.<DATA_TYPE> <DATA_CENTER> <NETWORK> <STATION>
<LOCATION> <CHANNELS> <START_TIME> <END_TIME>
To elaborate:
DATA_TYPE specifies what data are desired. This field
must always have a leading period, making the possible choices
".DATA", ".RESP", and ".INV". Note that more
data types may become available in the future.
DATA_CENTER is a unique string identifier representing
a specific data center in the group of networked data centers.
The proper data center code name must be used here in order to
match to the proper data center.This field may be wildcarded with
a single *. However, if the user insists that
data come from a specific data center, then putting an identifier
in this field would force the request line to be sent to that
site. (Here is a list of all the networks
and the data centers that act as the primary providers - it
looks like <network code>|<data center>.)
NETWORK is the FDSN network code (list)
for the data requested, consisting of one or two characters. This
field may be wildcarded.
STATION is a station name up to five characters in
length. This name refers to a geographic location, so occasionally
another network will have the same station name for their instrument
placed nearby. This is equivalent to the station identifier in
SEED format. The number of station names can vary from one to
any number of white-space separated elements. Each station entry
may be wildcarded. When two or more stations are specified, they
need to be enclosed in double-quotes. An example station string
would be:
"ANMO KIV B*"
LOCATION is an identifier that allows users to request
data from specific data streams on the instrument at the specified
network and station. This is in the form of a one or two character
string, referring to the location identifier in SEED format. This
field may be wildcarded. The number of location indentifiers can
vary from one to any number of white-space separated elements.
Each location identifier entry may be wildcarded. When two or
more location identifiers are specified, they need to be enclosed
in double-quotes. An example location string would be:
"00 01 02"
CHANNELS is a string describing the channels to be
retrieved. Channel names are up to three characters in length
and follow SEED channel-naming conventions. The number of channel
names can vary from one to any number of white-space separated
elements. Each channel entry may be wildcarded. When two or more
channels are specified, they need to be enclosed in double-quotes.
An example channel string would be:
"BHE LH? E*"
START_TIME is a six-field set of numbers specifying
the time and date for the beginning of the time window desired.
The format is:
"YYYY MM DD hh mm ss.ffff"
where YYYY = year (0000-9999), MM = month (01-12),
DD = day of month (01-31), hh = hour (00-23), mm
= minute (00-59), ss = second (00-59), ffff = fraction
of second (0000-9999 ten-thousandths). Take note that the ss
field can drop the decimal point if the fraction of a second is
equal to zero. Since this is a white-space separated set of characters,
the time string must be contained within double-quotes.
Wildcards are not allowed.
An example start time could be:
"1995 06 22 04 00 23.4522"
END_TIME has the same format as START_TIME, and pertains
to the end of the time window for the data desired.
Request Types
Inventory (.INV) Requests: Inventory
requests ask for information regarding the data holdings of a
particular data center.
Examples of .INV request lines:
.INV *
.INV GEOFON *
.INV GEOFON AA B*
.INV GEOFON AA TATO * *
.INV * IU "AAE ANMO" * * "1995 03 03 02 24 01.3"
"1995 03 03 07 00 30.0"
.INV * II KIV * "BHE BHN BHZ" "1996 05 01 00 00
00.0" "1996 05 01 05 00 00.0"
Looking at these sample inventory requests, you'll notice that
some of the request lines have less than the total number of fields
filled in. What this illustrates is the inventory request's unique
ability to accept a variable number of field entries which
will determine how much information is returned. Information is
displayed hierarchically. That is, what you don't include in your
request line - either explicitly or with wildcards - you don't
get. So, in our above example, the first request line would only
return a list of cooperating Data Centers, the second a list of
networks for the specified Data Center, the third line a list
of stations from network AA that begin with a B, etc., following
the request line format listed earlier in this
section.
Response (.RESP) Requests: Response
requests return detailed station and channel information to the
user in the form of a specially formatted ASCII text file. The
format mimics response files generated by the IRIS utility rdseed.
Unlike .INV request lines, the .RESP lines must include all
the field strings in the standard request line
format.
Example of a .RESP request line:
.RESP * G SSBC * * "1990 03 01 00 00 00" "1990
03 02 00 00 00"
Waveform (.DATA) Requests: A request
for waveform data may take considerably longer to process than
requests for inventory and response data. If the user has mixed
inventory or response request lines with waveform request lines,
the inventory and response data will generally be returned sooner
than waveform data. Unlike inventory requests, all
fields must be included in a .DATA request line, including
the start and end time, in order for the request line to be accepted.
The default output format for waveform data is binary SEED
format.
Example of a .DATA request line:
.DATA * II BFO * BHZ "1998 02 03 04 20 34" "1998 03 04 20 20
00"
MAILING A REQUEST
A NetDC request is completed by emailing the request to:
netdc@fdsn.org
Alternatively, the request can be emailed directly to user-id
netdc at any participating data center.
EXAMPLE REQUEST
.NETDC_REQUEST
.NAME Joe Seismologist
.INST University of Quakes
.MAIL 1101 Binary Data Way, Anytown, WA 90909
.EMAIL joe@host.seismolab.edu
.PHONE (999) 555-4567
.FAX (999) 555-4568
.LABEL My_Request
.MEDIA FTP
.ALTERNATE MEDIA EXABYTE 2GB
.FORMAT_WAVEFORM SEED
.FORMAT_RESPONSE SEED_ASCII
.MERGE_DATA YES 3
.DISPOSITION PULL
.END
.RESP * G SSBC * * "1990 03 01 00 00 00" "1990
03 02 00 00 00"
.INV NCEDC * *
.DATA * PS TSKO * M?? "1990 03 01 00 00 00" "1990
03 05 06 02 45.78"
.DATA * CD ZHLP * "B?? S??" "1986 06 16 00 00 00"
"1986 06 19 04 00 00"
SEE ALSO
NetDC Technical Manual, SEED Manual, rdseed,
list of network codes and primary data centers
version 10/29/1999
|