AutoDRM User Guide


		AUTODRM USER GUIDE		    Last updated: 2009-04-07

AutoDRM is an automatic, electronic mail-based message handling system
developed and maintained by the Canadian National Data Centre for Earthquake
Seismology and Nuclear Explosion Monitoring (CNDC) for the exchange of
seismic and other geophysical data.  It has been in continuous operation
since April 1994.  AutoDRM uses a command language that represents an
amalgam of the command set and structure of the original Swiss autodrm and
the GSE2.0 and IMS1.0 command sets (see below).  While every effort has been
made to allow the old commands to function fully, users are encouraged to
adopt the GSE/IMS command set since it is more powerful and flexible and is
an International Standard.  More information on GSE/IMS formats and
protocols are available on our Website at:

			http://earthquakescanada.nrcan.gc.ca

Anyone with e-mail access to the Internet can request information about the
Canadian National Seismograph Network (CNSN).  You may choose to have the
complete autodrm response returned immediately by e-mail, or receive a short
message that the output file is available at the CNDC for retrieval via
anonymous ftp.

To obtain information, simply send an electronic request mail to the
Automatic Data Request Manager (autodrm@seismo.NRCan.gc.ca).  To get
started with the latest version of this guide, you may send a message with
"HELP" or "PLEASE HELP" in the subject field, or bracketed by "begin" and
"stop" in the message body as follows:

BEGIN
PLEASE HELP
STOP

For general earthquake information, send e-mail to info@seismo.NRCan.gc.ca.
For a list of recent Canadian seismicity, finger info@seismo.NRCan.gc.ca.
Check out our Web page at URL http://www.seismo.NRCan.gc.ca/


The rest of this User's Guide discusses the following topics:

1) Message Format and Rules of Use

2) Naming of seismic (and related) data channels.

3) Description of Commands Understood by the CNDC AutoDRM

4) Examples

5) CNSN Data Citation Policy

6) Calibration Change in SEED Waveform Files

7) Time Corrections in Waveform Files

8) Generation of pseudo-Long Period data


==================================
1) Message Format and Rules of Use
==================================

- Commands may be entered in either upper or lower case, left justified,
  starting in column 1.  Typically only the minimum number of characters
  to uniquely characterize the keyword (>= 3) are required, but all
  examples shown follow the international autodrm convention.

- Required and optional arguments may follow the command in free format,
  separated by one or more blank spaces or tabs.

- All request messages must start with the BEGIN command, end with the
  STOP command, and should include an EMAIL or FTP command specifying a
  return address.  The only exception is the one-line HELP request.
  Blank lines and comment lines beginning with `#' are ignored.

- As of V5.0, multiple requests in the same mail message (i.e., multiple
  BEGIN/STOP sequences) are no longer supported.

- If no return e-mail address is given (via EMAIL or FTP), autodrm will
  attempt to reply to the mailer-supplied return address.  However, this
  is notoriously unreliable, especially across different mail systems,
  and return messages frequently never reach the requestor.

- Since autodrm commands are executed sequentially as they are encountered,
  it is important to set the "context" before initiating an action.  For
  example,  you must specify a date-time range *BEFORE* issuing the
  WAVEFORM command.  For the EMAIL and FTP commands, while it is not
  illegal to put them after a command that elicits a response, they will
  have no effect (until possibly later commands are executed).  This may
  mean your responses go astray (see preceding point).

- Commands specifying a range of values may use either " - " or " TO "
  interchangeably as the range separator.  DEPTH and MAGNITUDE can also be
  used with a single range value, provided the separator is present (see
  example 4)

- As of December 2004, all waveform data is retrieved very rapidly from
  a magnetic disk-based online archive.  To see the oldest available data,
  use the AVAIL command.  Requests exceeding the limit of on-line access
  may return only partial data.  The START_TIME (DATE1) must be earlier
  than the END_TIME (DATE2).

- There is currently a limit of 1000 solutions that may be retrieved from
  the database using the Bulletin and Event commands.  This is a
  precaution used to prevent nuisance or improperly-formed requests from
  spewing reams of useless information and negatively impacting the
  performance of our database system.  Legitimate users requiring more
  output are encouraged to contact us directly so we can screen their
  requests and provide guiding advice.  Send an e-mail to
  info@seismo.NRCan.gc.ca.

- The response message is copied to our anonymous ftp directory for
  retrieval whenever requested via the FTP command, the output file size
  exceeds 1MB, or SEED or CA format (binary) waveforms are requested.  An
  e-mail notification is sent noting the ftp address, location, and
  filename.

- To retrieve waveform files via ftp:
   - ftp to ftp.seismo.NRCan.gc.ca
   - login as user "ftp" or "anonymous" and supply your e-mail address when
     prompted for a password
   - cd to pub/autodrm
   - type "get <filename>" to retrieve the waveform file to your current
     working directory
   - type "quit" to exit ftp


================================================
2) Naming of seismic (and related) data channels
================================================

The unique naming of seismic (and related) data channels from Canadian 
stations follows an extension of the FDSN channel-naming conventions.  A
full channel name comprises three fields: a network code of up to 12
characters (eg., CNSN, POLARIS); a site code of up to 5 characters, and
a 3-character channel (band-gain-orientation) code, each separated by a
dot (`.').  These are defined separately by the NET_LIST, STA_LIST, and
CHAN_LIST commands respectively.

If network list is not specified, the list defaults as before to all open
networks/deployments (currently CNSN, POLARIS, FEDNOR and CHASME).


=========================================================
3) Description of Commands Understood by the CNDC AutoDRM
=========================================================

Commands are followed by a number in parentheses (n) interpreted as
follows:

  1 - original (Swiss) autodrm command set
  2 - GSE2.0 (1995) command set
  3 - local extensions not necessarily recognized by other autodrm's
  4 - new or changed commmands for IMS1.0

Command         Argument(s)     Meaning
-------         -----------     -------

AIDE				Send the French Language version of this
				Users Guide as a separate e-mail.
				

ARRIVAL(2)      GSE2.0          Requests a list of phase arrival data
				associated with origins (epicentre
				solutions) qualified by the specified time
				range and station and channel lists.


AVAIL(3)                        Requests the time of the earliest waveform
				data available on-line.  Note: this time
				changes every half hour as new data is added
				and old data dropped from the on-line disk
				area.


BEGIN(1/2)      GSE2.0          Required to denote the start of a new
				request and initiate command processing.
				The GSE2.x argument here forces the
				interpretation of certain commands and the
				output format to use the GSE2.x standard.


BULLETIN(2)     GSE2.0          Requests generation of a list containing
				ORIGIN (epicentre solution) and phase
				ARRIVAL data matching the specified time,
				latitude, longitude, depth, and magnitude
				ranges.


CHANNEL(2/4)    GSE2.0/IMS1.0   Requests a list of channel-related
				information (sensor type, emplacement, etc.)
				for the specified STA_LIST, CHAN_LIST and
				latitude and longitude ranges.  Replaces
				SLIST(1).


CHAN_LIST(2)    channels        CNSN channel names comprise a 3-character
				channel (band-gain-orientation) code,
				following the FDSN channel naming
				conventions.  Lower case is allowed.
				CHAN_LIST replaces the `chan' portion of
				the stn-chan list on the old WAVEF
				command.  Stations are specified separately
				using STA_LIST.  Default for GSE2.0 is all
				vertical components (*Z).  See WAVEFORM for
				examples.


DATE1(1/3)      yyyymmddhhmmss  Define date-time of the start of a time
START_TIME(3)                   interval: (yyyy: year, mm: month, dd: day,
				hh: hour, mm: minute, ss: second.  Note
				that the time portion need only be
				specified to the precision desired; the
				date portion is required.  As a local
				extension, punctuation may be used to
				separate the time fields for readability.
				See also TIME(2) command.  Unlike TIME, no
				spaces are allowed in the time string.

DATE2(1/3)      yyyymmddhhmmss  Define date-time of the end of a time
END_TIME(3)                     interval.  Format and caveats same as for
				DATE1 above.


DEPTH(2)        dep1 - dep2     Sets search range for depth in kilometers
				(positive downwards), from shallow to
				deep.  Defaults to all.


DEPTH_MINUS_ERROR(2)            Selects events that have a 90% probability
		dep1 - dep2     of being within the depth range specified
				(in kilometers, positive downwards).
				Defaults to range -999 TO 9999 (all).


DETECTION(2)    GSE2.0          Requests generation of a list of
				detections.  At present, only Yellowknife
				Array data are available in GSE2.0 format.

		CNSN            Requests a list of preliminary detections
				from the automatic CNSN event detector.  A
				time range <= 24 hours and younger than 1
				year is required.  A station list must be
				supplied.


DURATION(3)     seconds         As an alternative to DATE2, DURATION
				specifies an interval of time.  It must be
				used with DATE1 to fully specify a date-time
				range.


EMAIL(1)        e-mail_adr      Specify preference for e-mail data
E-MAIL(2)                       transmission and supply a return e-mail
				address.  Messages longer than 1 Megabyte
				will be sent via ftp with a brief e-mail
				notice.  Must appear before the NET_LIST
				command.


END_TIME(3)                     See DATE2.


EVENT(2)        GSE2.0          Requests generation of a list containing
				the single preferred ORIGIN (epicentre
				solution) data matching the specified time,
				latitude, longitude, depth, and magnitude
				ranges.


EVENT_STA_DIST  dist1 - dist2   Restricts search range for bulletin-type
				requests and/or waveform data associated
				with specific events to event-station
				distances in degrees that lie within the
				specified range.  Defaults to range 0 - 180
				(all).


FORMAT(3)       SEED            Local command used to specify format for
				output waveforms.  If SEED format is
				requested, a SEED V2.3 format (binary) file
				is created and the ftp option is forced.
				NOTE: If you use IRIS's RDSEED program to
				remove instrument response from CNSN data in
				SAC, only RDSEED versions <= 4.12 or >= 4.6
				do this correctly.

		CSS             Return waveforms in CSS format.  The
				site, w, and wfdisc files are combined into
				a single Zip archive for easy download and
				the ftp return option is forced.

		GSE2.0          Return waveforms in GSE V2.0 format.
				Currently only CM6 compressed ASCII format
				is supported (see CODECO program returned
				by SOURC for decompression routine in
				FORTRAN).

		IMS1.0          Return waveforms in IMS V1.0 format, with
				extra STA2 and OUT2 records as required.
				Currently only CM6 compressed ASCII format
				is supported (see CODECO program returned
				by SOURC for decompression routine in
				FORTRAN).

		CA              Return waveforms in "Canadian Archive" (CA)
				format, a compressed binary format
				developed by the GSC originally for the
				CNSN, and now used more widely as a common
				archive format.  Contact us for
				decompression routines in C.

		INT             Return waveforms as ASCII integers.  Each
				channel is saved as a separate ASCII file
				comprising a short header containing the
				channel name in the format
				station.component (i.e. WALA.BHZ), the
				start time of the earliest data in the
				file, the sample rate and the number of
				samples, followed by the integer sample
				values, one value per line. All files are
				combined into a single Zip archive for easy
				download and the ftp option is forced.

FTP(2)          e-mail_adr      Specify data return via ftp and supply
				e-mail address for a brief notice.
				Requested data will be stored at
				ftp.seismo.NRCan.gc.ca, for access via
				anonymous ftp.  No EMAIL command is
				required.

				To avoid disk space problems, users are
				strongly advised to delete waveform files
				using the remote file DELETE command in ftp
				once they have retrieved them.  Note that
				files in the ftp directory are cleaned up
				automatically after a period of time
				(currently three days).



FTP_PATH(3)      path		Used with INTER (below), specifies the path
				for anonymous ftp to write the response on the
				user's ftp directory (e.g. /imports/user).
				
				
HELP(1/2)                       Send this Users Guide as a separate e-mail.
GUIDE(1)                        Same as command HELP.
PLEASE HELP(1)                  Same as command HELP.


INTER(1)	IP_number	Requests the automatic "push" of the response
				by anonymous FTP to the internet-address
				given by 'IP_number'.  This address should be
				specified in numerical form as in the
				/etc/hosts file on UNIX-machines, ( e.g. 
				INTER 129.132.53.4 ).  Can be used with
				the FTP_PATH and OUT_FILE commands to specify
				an output path and filename.  Note: proper
				permissions must be granted for anonymous
				ftp to write to this path.


LAT(2)          lat1 - lat2     Sets search range for latitude in degrees,
				from lower (south) to higher (north).
				Southern latitudes are negative.  Defaults
				to all.


LONG(2)         long1 - long2   Sets search range for longitude in degrees,
				from west to east.  Western longitudes are
				negative.  Defaults to all.


MAG(2)          mag1 - mag2     Sets magnitude search range, from lower to
				higher.  Defaults to all.


MAG_TYPE(2)     MN, MS, ML...   Specifies a list of magnitude types to
				qualify a search with the magnitude
				environment.  Currently the CNDC calculates
				MN, MC, MS, ML and mb, but stores magnitude
				types from other agencies as well.
				Defaults to all.


MSG_ID(2)       unique_id       Up to 20 char ID used as a convenience for
				the sender in tracking messages.  Value is
				returned in the response message in a
				"REF_ID" line.  Structured replacement of
				TITLE/SUBJEct(1).  Third line of a GSE2.x
				request message.


		source          Optional 2nd parameter for source ID up to
				eight characters.  For GSE2.x, National
				Data Centres conventionally use a 3-char
				country code followed by "_NDC".  Our
				responses will contain source "CAN_NDC".


MSG_TYPE(2)     request/data    Used as the second line of a GSE2.x request
				message to specify and distinguish REQUESTs
				(what users send to an autodrm) from the
				DATA autodrm provides.  Necessary for fully
				automated systems, where both requests and
				responses are machine-generated and
				interpreted.


NET_LIST(3)     network(s)	New for V5, this command allows fine-tuning
				requests beyond the default list of open
				networks/deployments:  CNSN, POLARIS,
				FEDNOR and CHASME.  Must appear before the
				STA_LIST command.
				
NONOTIFY(3)			Used with the INTER command for anonymous
				FTP "push", indicates that no informative
				e-mail reply is desired.  Note: this should
				be used only after careful testing to ensure
				proper results.
				

ORIGIN(2)       GSE2.0          Request generation of a list containing
				Origin (epicentre solution) data matching
				the specified time, latitude, longitude,
				depth, and magnitude ranges.  There may
				give more than one solution for the same
				event.


OUTAGE(2/4)     GSE2.0/IMS1.0   Request a list of data outage by stn_chan.
				Short-term (<60s) outages are reported
				statistically, and longer-term outages are
				reported individually.


OUT_FILE(3)     filename        Local command to specify a unique filename
				for the user's response data for FTP pull
				or push.  If no filename is given,  autodrm
				will choose one based on date-time of the
				request.  Note that files in the CNDC ftp
				directory are cleaned up automatically
				after a few days.


RESPONSE(2)     GSE2.0          Requests response information in the form
				of tables of system sensitivity, poles and
				zeros and FIR filter coefficients that can
				be cascaded to derive the complete response
				of the instrument.

				Complete response information is also
				contained in the station control record
				portion of SEED format waveform files.

				The CNDC also maintains in the anonymous
				ftp directory (ftp/exports) a FORTRAN
				subroutine called cnsn_response.f, that can
				be used to generate response values for all
				CNSN stations.


SLIST(1)                        Request a list of station-related
				information (site, location, dates of
				operation, etc.) for the specified STA_LIST
				and latitude and longitude ranges.
				Replaced by and now synonymous with
				STATION(2).


SOURC(1)                        Request FORTRAN source code of the CODECO
				program, that decompresses the GSE formats,
				in a separate e-mail.


STATION(2/4)    GSE2.0/IMS1.0   Requests a list of station-related
				information (site, location, dates of
				operation, etc.) for the specified STA_LIST
				and latitude and longitude ranges.
				Replaces SLIST(1).  The GSE2.1 format
				includes network code.


STA_FILE(3)     filename        Specifies a file containing a list of
				stations to be used in place of repetitive
				and/or lengthy STA_LIST commands.  Frequent
				users may arrange with CNDC staff to set
				up this file.


STA_LIST(2)     stations        CNSN station codes comprise a site name of
				up to 5 characters registered with the NEIC
				and the ISC.  Lower case is allowed.
				STA_LIST replaces the `stn' portion of
				stn-chan list of the old WAVEF command.
				For GSE2.x, channels must be specified
				separately using CHAN_LIST.  A list of up
				to 40 stations may be supplied, separated
				by spaces and /or commas.  Present default
				for GSE2.x is all stations (*).  See
				WAVEFORM for examples.


START_TIME(3)                   See DATE1.


STOP(2)                         Required to denote the end of the current
END(3)                          message and the generation of output.


SUBJE(1)        your_subject    The response mail returned to you will have
TITLE(1)                        the subject you specify here; if not
				specified, a default reference ID will be
				supplied.


TIME(2)         time1 - time2   Specifies a date-time range.  GSE2.x time
				format comprises separate date and time
				fields, separated by one or more blanks,
				with values of the form "yyyy/mm/dd
				hh:mm:ss.sss".  Leading zeros in all
				numeric fields are required.

				Replaces DATE1/DATE2.  As with DATEx, only
				the date portion is required; the time
				portion need only be specified to the
				precision desired.  Defaults to 1970/1/1
				00:00:0.000


TIME_STAMP(4)                   Requests that data messages be time
				stamped.  Time stamps will appear at the
				beginning and end of each data type,
				recording the UT time (to the second) that
				processing took place.


WAVEFORM(2/4)   format          Request all waveforms for the station-
				channels previously specified with
				STA_LIST and CHAN_LIST commands and
				specified time range in the specified
				format (see FORMAT command above for
				options).

WAVEF(1)        	        As of AutodDRM V5 the stn-chan option is 
                                no longer supported.  Use STA_LIST and
                                CHAN_LIST.
                                
                                
The CNDC AutoDRM command set may be modified from time to time.  It is
recommended that you re-request this Guide periodically or in case of
problems in order to keep up to date with the latest developments.


===========
4) Examples
===========

1.  Request a complete list of current CNSN stations in IMS1.0 format:

BEGIN
EMAIL yourname@abc.efg.hi
NET_LIST CNSN
STATION IMS1.0
CHANNEL IMS1.0
STOP

2.  Request a list of all high broad-band channels in the POLARIS
    network.
    
BEGIN
EMAIL yourname@abc.efg.hi
NET_LIST POLARIS
CHAN_LIST HH*
CHANNEL IMS1.0
STOP    


3.  Request 2 minutes of waveform data for all 3 components of
    stations INK, WALA, and RES in the default GSE compressed format, by
    return e-mail:

a) original command set (will return V1: GSE)

BEGIN
EMAIL yourname@abc.efg.hi
TITLE test.eg2a
DATE1 200111090000
DATE2 200111090002
WAVEF INK WALA RES
STOP

b) GSE2.0 command set (will return V2: GSE2)

BEGIN GSE2.0
EMAIL yourname@abc.efg.hi
MSG_TYPE REQUEST
MSG_ID test.eg2b
TIME 2001/11/9 00:00 TO 2001/11/9 00:02
STA_LIST INK WALA RES
CHAN_LIST *
WAVEFORM
STOP


4.  Request 10 minutes of vertical-component waveform data for station WALA
    in SEED format (NB: SEED data is always placed in the anonymous ftp
    directory as separate files, with a mail notification):

 a) Simplest and most straight-forward, using local DURation and FORMAT
    commands

BEGIN
EMAIL yourname@abc.efg.hi
DATE1 20011030.0000
DUR 600
FORMAT SEED
STA_LIST WALA
CHAN_LIST *Z
WAVEFORM
STOP

 b) Using strict GSE2.0 command set (NB: CHAN_LIST not required since
    vertical-only channel is GSE2.0 default)

BEGIN
EMAIL yourname@abc.efg.hi
TITLE test.eg3a
DATE1 2001/10/30_0000
DATE2 2001-10-30:00:10
FORMAT SEED
WAVEF WALA.*Z
STOP



 c) Using strict GSE2.0 command set (NB: CHAN_LIST not required since
    vertical-only channel is GSE2.0 default)

BEGIN GSE2.0
E-MAIL yourname@abc.efg.hi
MSG_TYPE REQUEST
MSG_ID test.eg3b
TIME 2001/10/30 00:00 TO 2001/10/30 00:10
STA_LIST WALA
CHAN_LIST *Z
WAVEFORM SEED
STOP



5.  Search the National Earthquake Database and return a list of origins
    and associated phase arrivals for all events occurring in the northern
    hemisphere between June 1, 1993 and August 31, 1994 having magnitude 5
    and greater, and a focal depth less than or equal to 20 km, for which
    MN and ML magnitudes were calculated, in GSE2.0 format:

BEGIN
EMAIL yourname@abc.efg.hi
MSG_ID test.eg4
TIME 1993/06 - 1994/09
LAT 0 - 90
MAG 5 -
DEPTH  - 20
MAG_TYPE MN ML
BULLETIN GSE2.0
STOP

Notes:

1) You must substitute your own e-mail address for "yourname@abc.efg.hi".


============================
5) CNSN Data Citation Policy
============================

AutoDRM makes data from the GSC's Canadian National Seismograph Network
(CNSN) and CHASME experiment, plus data from other cooperating networks
(POLARIS) available FREE to anyone on the Internet.  In order for us to
maintain this service, we need to enlist the support of our users.  Please
include a citation to "The Geological Survey of Canada" in your work.  It
would be helpful if you would send a citable reference for any publications
that use CNSN data to John Cassidy (cassidy@pgc.NRCan.gc.ca), who is
maintaining a database of CNSN data usage.  Alternatively, you could send
a paper or electronic reprint to him:

Dr. John Cassidy
Pacific Geoscience Centre
P.O. Box 6000,
9860 West Saanich Road,
Sidney, B.C.
V8L 4B2


============================================
6) Calibration Change in SEED Waveform Files
============================================

On Monday October 3, 1994 at 17:45, the CNSN Data Acquisition software was
modified to remove a scaling factor (transmission gain) of either 2**5 = 32
(most sites) or 2**8 = 256 (BBB, PGC, PNT).  Yellowknife Array sites (YK*)
are not affected.  This has the effect of dividing each sample value by a
factor of 32 or 256.  Correct response information is written into the SEED
file headers.


=====================================
7) Time Corrections in Waveform Files
=====================================

SEED format waveform files created since Sep 12/94 have time correction
information incorporated into the Data Header records.  Note - these are
*logged* but not applied.

GSE format files, which have no time correction field, have had these time
corrections *applied*.  As a consequence, the data start time for some
stations may be shifted a number of seconds.  (NOTE: stations whose timing
is uncertain are flagged with a correction of 999.9 seconds!)

The CNDC maintains an historical record of time corrections in a file in
our ftp/exports directory called cnsn_clock_history_DATE (where the DATE
reflects last update).


========================================
8) Generation of pseudo-Long Period data
========================================

While we do not directly record 1 Hz long-period data, we do have the
capability to generate pseudo-channels of long-period data by filtering
and decimating the 40 Hz BH* and 100 Hz HH* data streams.

To obtain LP data, specify channel names of "LH*".


###########################################################################