############################################################################### 1 July 2003 USERS GUIDE OF THE A U T O D R M FOR GEONET, NEW ZEALAND Based on the original user's guide from the Swiss Seismological Service 17 June 1998. ----------------------------------------------------------------------- This users guide consists of three parts: - Part 1 is about electronic mail to and from the AutoDRM - Part 2 explains the complete command set understood by AutoDRM - Part 3 gives illustrative examples of request mails in both the 'old' and new GSE2.0 format (this part is especially for those who do not want to read the whole text!). 1) Sending and receiving electronic mail from AutoDRM ===================================================== In order to obtain data from GeoNet, you simply send an electronic request mail to the Automatic Data Request Manager (AutoDRM): E-mail address of the AUTODRM: * on Internet : autodrm@geonet.org.nz The request e-mail must contain commands (starting at column 1), depending on what you would like to receive. Minimum requirements are: * The first line must start with : BEGIN * Any line in between starts with: EMAIL emailaddress * The last line starts with : STOP where `emailaddress` is your e-mail address. NOTE: If you are not sure how your return address should look like for our machine, simply send a mail to the AutoDRM with the text 'HELP'; this text may be either in the subject or in the body of the request-mail. The AutoDRM will then send the correct return address back to you! * The response of the AutoDRM is sent to you via electronic mail. For requests which result in large responses (> ~ 100 kilobytes), you must specify an option (FTP): If this option is set, AutoDRM sends the data automatically via FTP to you, OR, if you prefer, the response is stored at our computer and you only get a short e-mail, providing you with the filename of the response and a detailed description on how you may transfer the response file by yourself to your computer using FTP (File Transfer Protocol). A more detailed description about this option can be found in part 2 of this users guide. * Precautions In order to avoid endless loops and other inconvenient things, no response mails are sent to requestors with the name POSTMASTER, MAILER-DAEMON or AUTODRM. Furthermore, an identical request from the same user is not processed if the second request arrives within the same 10 minutes. 2) Description of the commands that are understood by AutoDRM ============================================================= BEGIN First line in every request to AutoDRM. This command will cause the AutoDRM to respond in the 'old' AutoDRM-language. However, AutoDRM understands both request commands in the old and the new (GSE2.0) format. BEGIN GSE2.0 First line in a GSE2.0-request. This command causes this AutoDRM to respond in the 'GSE2.0-AutoDRM-language'. However, AutoDRM understands both request commands in the old and the new (GSE2.0) format. MSG_TYPE request Should be the second line of a request, if user wants to follow GSE2.0 formats. This line is optional on *this* AutoDRM but not at others (as e.g. the GSETT-3 IDC). MSG_ID your_msg_id source_id Third line of a request message, if user wants to follow GSE2.0 formats. The message_ID of the sender; may be up to 20 characters long. This message_id and the source_id will appear as the reference_id (REF_ID) in the response! The souce_id's are specified in the GSE2.0 documentation (max. 7chars) This line is optional on *this* AutoDRM but not at others (as e.g. the GSETT-3 IDC). E-MAIL email@address.of.the.user E-Mail address where response should be sent to. E_MAIL email@address.of.the.user same as E-MAIL command EMAIL email@address.of.the.user same as E-MAIL command GUIDE Send the information (User's Guide) printed here. INFOR Same as command GUIDE. HELP Same as command GUIDE. FTP email@address.of.the.user Instead of the 'E-MAIL' command: Send only short note via e-mail to the requestor and store the response locally on ftp-directory. (--> This is the new GSE2.0 format) FTP filename Note that command 'FTP' has two meanings, depending whether the request is in the 'old' format or in GSE2.0 format (GSE2.0 format: see above). This command sets the ftp option. If you also give your internet-address (see command INTER, below), the response will be automatically transferred to you via FTP. It is assumed you have an anonymous ftp-account (user=ftp, password=ftp). Your 'filename' also may contain a path and should point to a directory/file with appropriate write-access (Example: FTP pub/response.fil ). You will get a short note with the output of the FTP-command via e-mail. If you do NOT give your internet-address, the response will be archived on a special file; however, because there may already exist a file with your suggested name 'filename', AutoDRM will recognize this and give a unique name to the file. Only a short mail is sent to the user. This mail contains the filename of the archived response file and a description on how to transfer the file to the user's computer using FTP (File Transfer Protocol) via TCP/IP. (--> This is the old AutoDRM format) FTP Basically the same as FTP, but AutoDRM will choose a filename for you (because the filename is missing). (--> This is the old AutoDRM format) INTER IP_number If the option FTP is set, this command tells AutoDRM to automatically transfer the response to the FTP-account at the internet-address given here as 'IP_number'. This address should be given in the numerical form as in the /etc/hosts file on UNIX-machines (Example: INTER 129.132.53.1 ) (--> This is the old AutoDRM format) TIME [StartDateTime] TO [EndDateTime] Definition of Start- and End-DateTime Format: 1994/02/24 16:23:50.20 If EndDateTime is omitted, the current DateTime is assumed. Instead of the TIME command you may also use the DATE1 and DATE2 commands! DATE1 yyyymmddhhmm Define start of the time interval ('yyyy': year, 'mm': month, 'dd': day, 'hh': hour, 'mm': minute; Example: 24 Feb 1992 15:46 is: DATE1 199202241546). DATE2 yyyymmddhhmm Define end of the time interval ('yyyy': year, 'mm': month, 'dd': day, 'hh': hour, 'mm': minute; Example: 24 Feb 1992 15:46 is: DATE2 199202241546). STA_LIST ABC [,DEFG] [,HIJK] Definition of stations desired (multiple station codes must be separated by commas). No default. CHAN_LIST SHZ [,SHN] [,SLZ] Definition of channels desired (multiple channel IDs must be separated by commas). Default: *Z AUX_LIST [aux1] [,aux2] Definition of 'auxiliary' ID's (multiple auxiliary IDs must be separated by commas). WAVEFORM [GSE2.0|SEED|MSEED] Get waveforms for specified Time/Channels Waveforms are supplied from our continous recordings - if no continous data is available, the event-file archive is searched for data. Data may be requested in the following formats GSE2.0, SEED, MSEED (miniSEED). WAVEF stn Similar to command WAVEFORM GSE2.0, but no STA_LIST is required (station stn' is defined on the command line). Valid station names may be obtained using the command SLIST (see there). Multiple lines with this command (for additional stations) are allowed. This command must be preceeded by either the command TIME or the commands DATE1 and DATE2. STATION GSE2.0 Get station-info for specified stations (specifiy by using STA_LIST and CHAN_LIST environment commands). CHANNEL GSE2.0 Get channel-info for specified channels (specifiy by using STA_LIST and CHAN_LIST environment commands). RESPONSE GSE2.0 Get response-data (calibration) of the specified stations/channels (specifiy by using STA_LIST and CHAN_LIST environment commands). BULLETIN GSE2.0 Get bulletin-data for the specified TIME environment. ORIGIN GSE2.0 Get origin-data for the specified TIME environment. ARRIVAL GSE2.0 Get arrival-data for the specified TIME environment. CALIB stn Similar to command RESPONSE GSE2.0, but but no STA_LIST is required (station stn' is defined on the command line). The calibration is sent as poles and zeros (PAZ) plus a scale factor and allows you, to deconvolute the received waveform into displacement. If a DATE1 command is received, then the transfer function for this date is sent; otherwise the transfer function for the current date is used (Note: At the Swiss Seismological Service we keep track of any changes in the transfer functions with respect of time). Multiple lines with this command (for additional stations) are allowed. OUTAGE GSE2.0 Get outage-info on specified channels (TIME and STA_LIST environment required). TITLE your subject The response mail returned to you will have the subject you specify here; if not specified, a default subject is used (Swiss AUTO_DRM Response). SUBJE your subject Same as command TITLE . DETEC Send a list of all detections (and locations, if the event was located) made within the specified time interval. (For each detection we store 180 seconds of data of all channels.) This command must be preceeded by either the command TIME or the commands DATE1 and DATE2. AMI A Send a list of the most recent locations of the 'Alert Message Informations' received. Locations possibly belonging to same event are grouped together. Optionally a time interval (TIME or DATE1 and DATE2) may be specified to filter the output. If no time interval is specified, the first 100 lines are sent. SOURC CODECO Send the FORTRAN source code of program CODECO, which allows the conversion between various GSE-formats. The program contains the compression and decompression routines used by the GSE (Group of Scientific Experts) at the CD (Conference on Disarmament, Geneva). Using this program makes it easy to read and decompress the data files received from the AUTODRM. Attention: GSE2.0 format is supported but has not yet been fully tested (please note, that the information contained in the waveform-headers of the old GSE- and the new GSE2.0 format is not the same and therefore some information might be either lost or be unknown when converting between the 2 GSE-formats). Compression and decompression routines are working in both formats and have been tested. PPICK stn Send the P-picks of station 'stn' for all the detected events within a time interval. The P-picks (arrival times) are marked as 'manual' or 'automatic' picks. This command must be preceeded by either the command TIME or the commands DATE1 and DATE2. AVAIL Send a list of detections (without locations) of which (within the specified time interval) waveform data is available. This command must be preceeded by either the command TIME or the commands DATE1 and DATE2. SLIST Send a list of stations for which waveforms and/or calibration data is available. The station list also contains the coordinates of the stations. STOP This must be the last line of any request 3) Examples of AUTODRM request mails one may send to autodrm@geonet.org.nz =============================================================================== Example 1: --------- Request the user's guide. Command line: Meaning: BEGIN GSE2.0 Start of a request MSG_TYPE request This is a request MSG_ID ANY_NDC Your ID EMAIL Your e-mail address GUIDE Send this file STOP End of request Example 2: --------- Request station and channel information. BEGIN GSE2.0 Start of a request MSG_TYPE request This is a request MSG_ID ANY_NDC Your ID EMAIL Your e-mail address STA_LIST * Define station(s) CHAN_LIST * Define channel(s) CHANNEL Channel-info needed STOP Example 3: --------- This sample mail shows how to retrieve waveform data in SEED format. Command line: Meaning: BEGIN GSE2.0 Start of a request MSG_TYPE request This is a request MSG_ID ANY_NDC Your ID EMAIL Your e-mail address FTP Your e-mail address STA_LIST * Define station(s) CHAN_LIST SHZ Define channel(s) TIME 1986/12/31 00:00:01 TO 1987/01/01 00:00:01 Define time interval WAVEFORM SEED Get waveform data in SEED format STOP End of the request Data Formats The GeoNet AutoDRM supports three data formats for the extraction of waveforms; GSE2.0, SEED, and miniSEED. Data may be requested in these formats by supplying one of the following arguments to the WAVEFORM parameter of the request email: GSE2.0, SEED, MSEED. GSE2.0 GSE2.0 was developed for use in the GSE's Technical Test 3 (GSETT-3), which was a trial starting on 1 January 1995 of a global system for monitoring nuclear explosions. A description of the format is available at http://www.css.gov/web-gsett3/CRP-243/www/FmtProt/FmtProt_1.html. Various tool for manipulating GSE2.0 files are available from href="http://orfeus.knmi.nl/other.services/conversion.shtml. SEED and MSEED The Standard for the Exchange of Earthquake Data (SEED) is an international standard format for the exchange of digital seismological data. miniSEED (MSEED) files are data only SEED Volumes. The SEED manual and a description of the miniSEED format is available from http://www.iris.washington.edu/manuals/SEED_chpt1.htm. Tools for reading SEED volumes, enabling conversion of SEED to SAC (binary or ascii), AH, SEGY, CSS, miniSEED or fullSEED are also available from http://www.iris.washington.edu/manuals/rdseed.htm. UUENCODE Files created by the GeoNet AutoDRM are uuencoded. Uuencode converts a binary file into an encoded representation that can be sent using electronic mail. The SEED or miniSEED data volume must be extracted from the uuencoded file either using uudecode, or, for Windows users, a suitable archive management tool such as winzip (http://www.winzip.com) or pkzip (http://www.pkware.com). Instead of 'E-MAIL your@mail.address' you may also specify FTP your@mail.address; then you recieve only a short message and the actual response is stored locally (to be retrieved later via FTP). Note: If 'BEGIN GSE2.0' is specified, the format-options of the commands WAVEFORM, STATION, CHANNEL, RESPONSE, and OUTAGE default to GSE2.0 and therefore the format-specification 'GSE2.0' is optional! NOTE: - All command lines must start on column 1 - The BEGIN command is absolutely necessary (unless you send the HELP command)! - The commands WAVEF, DETEC, AVAIL, and PPICK m u s t be preceeded by either the TIME or the DATE1 and DATE2 commands. - AUTODRM response mails are limited to a size of approximately 100 kilobytes UNLESS the FTP-option is used. If your request would produce a larger response mail, the number of waveforms sent will automatically be reduced and an error message will appear. Therefore: use the FTP-option or SPLIT your requests (see below)! - A request mail may contain several requests; each request must start with the command BEGIN, must end with the command STOP and should have the command EMAIL with the e-mail address. The response of each request is sent by a separate e-mail in order to keep the message size small. - Only one time interval (DATE1 & DATE2) per request is allowed, if you use the old 'WAVEF stn'; if you use the STA_LIST and TIME environment, followed by the WAVEFORM command, you may use multiple TIME intervals! - The presence of a SUBJECT in the incoming request mail is not necessary. However, if there is a subject, it is ignored. ###############################################################################