# Earthworm Modules:
ewhtmlemail Configuration File Commands

(last revised May 12, 2015)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Style file format

On startup, ewhtmlemail reads the configuration file named on the command line. Commands in this file set up all parameters. In the control file, lines may begin with a valid ewhtmlemail command (listed below) or with one of 2 special characters:

>     #  marks the line as a comment (example: # This is a comment).

>     @  allows control files to be nested; one control file can be
>        accessed from another with the command "@" followed by
>        a string representing the path name of the next control file
>        (example: @pick_ew.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).
ewhtml also uses a specific configuration file, ewhtmlemail.css, which is added to the alert emails as a style sheet. This file is read whenever a new html email is generated.

## 1. EXAMPLE CONFIGURATION FILE

    #
    #                    ewhtmlemail's configuration file
    #
    MyModuleId       MOD_EWHTMLEMAIL        # This instance of ewhtmlemail
    InRing           HYPO_RING              # Transport ring to find hyp2000arc msg
    HeartbeatInt     30                     # Heartbeat interval in seconds
    LogFile          1                      # If 0. don't write logfile; if 1. do
    Debug            0                      # If 1, print debugging msgs
    DebugEmail       0                      # If 1, echo the email command used
    GetLogo  INST_WILDCARD  MOD_WILDCARD    # Limit the sources of hyp2000arc msgs
    MaxMessageSize   16384                  # hyp2000arc messages can be very large
    site_file        cvarg.hinv             # hypoinverse format to locate stations
    HTMLFile         ~/ewhtmlemail/em       # html file folder and format
    EmailProgram     /usr/sbin/sendmail     # sendmail or blat.exe
    UseBlat                                 # Specifies use of blat.exe
    EmailRecipient   recipient1@email.com   # List of email recipients, maximum 20
    EmailRecipient   recipient2@email.com
    EmailRecipient   recipient3@email.com
    EmailRecipientWithMinMag test4@mail.com 2.0             # only send if magnitude is >= 2.0
    EmailRecipientWithMinMagAndDist test5@mail.com 2.0 3.0  # only if mag is >= 2.0 and dist from event <=3km
    StyleFile        ~/ewhtmlemail.css      # Location of the style file
    MAX_SAMPLES      100000                 # Maximum sample count to request
    WSTimeout        5                      # Waveserver timeout in seconds
    WaveServer 192.168.0.1:16022            # List of waveservers, maximum 10
    WaveServer 192.168.0.2:16022            # format aaa.bbb.ccc.ddd:portno
    TimeMargin 10.0            # time margin (in seconds) for downloading from waveservers (default 10)
    MaxDuration 60.0           # maximum duration (in seconds) of trace (default 144)
    TraceWidth 1200            # sets width of traces (default 600)
    TraceHeight 200            # sets height of traces (Default 60)
    UseML                      # optional flag to turn on TYPE_MAGNITUDE (localmag) use
    UseMW                      # optional feature to turn on TYPE_MAGNITUDE and detect MW magnitude messages
    MagWaitSeconds   200       # optional delay before releasing an email that may have an ML or MW
    DataCenter       "My data Center" 	# optional DataCenter value used in the table header
    MinQuality       C			# only show C or better quality events
    StaticMapType    satellite              # map type for the google static map
    SubjectPrefix "Preliminary Location"    # optional subject prefix for emails (defaults to EWalert)
    UseUTC                     # optional flag to use UTC in the emails (localtime zone of PC is default)
    ShortHeader                # optional flag to compress the header table and leave less whitespace
    ShowDetail                 # optional flag to show more event information (errh, errz, gap, rms, etc)
    DontShowMd                 # optional flag to remove Md from the report
    DontUseMd                  # optional flag to not use Md for email decisions for any EmailRecipientWithMinMag
    UseRegionName              # optional flag to use flynn-enghdal region names in table at top of email
    CenterPoint 45.0 -121.0    # optional lat and lon for EmailRecipientWithMinMagAndDist
    SPfilter                   # optional flag to enable shortperiod filtering
    GMTmap                     # optional flag to produce GMT data
    Mercator                   # Mercator projection for GMT map (default)
    Albers                     # Albers projection for GMT map
    StationNames               # show station names in the GMT map
    Cities /home/earthworm/run/params/cities.txt             # cities to be printed in the GMT map
    MapLegend /home/earthworm/run/params/ewhtmlemail.legend  # map legend to be drawn in the GMT map
    KML ${EW_DATA_DIR}/web/kml web/kml_preamble.txt          # dir for kml file and kml preamblefile
    BlatOptions "-server localhost:1099 -profile gmailsmtp"  # optional blat settings (i.e., stunnel, gmail smtp)

## 2. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by ewhtmlemail, grouped by the function they influence. Not all of the commands are required and they may be specified in any order.

    	Earthworm system setup:
    +		MyModuleId		Module id for pick_ew (mandatory)
    +		InRing		Shared memory region for input (mandatory)
    +		HeartBeatInt 	Interval between heartbeats (mandatory)
    +		GetLogo 	Control message sources (mandatory)
    +		MaxMessageSize 	Maximum size of incoming HYP2000ARC messages (mandatory)

    	Processing:
    +		site_file 	Hypoinverse stations file (mandatory)
    +		HTMLFile 	Output folder and prefix for html file (mandatory)
    +		EmailProgram 	Location of the sendmail program (optional)
    +		UseBlat 	Specifies use of blat.exe (optional)
    +		EmailRecipient 	List of email recipients (optional)
    +		StyleFile 	Location of the style sheet file (optional)
    +		WaveServer 	Waveserver address (optional)
    +		MAX_SAMPLES 	Maximum number of samples to request (optional)
    +		WSTimeout 	Waveserver timeout (optional)
    +		UseML 		Flag to turn on TYPE_MAGNITUDE (localmag) use (optional)
    +		UseMW 		Flag to turn on TYPE_MAGNITUDE (MW) use (optional)
    +		MagWaitSeconds 	Delay before releasing an email (optional)

    	Output Control:
    +		LogFile		Log flag (mandatory)
    +		Debug		Debugging flag (optional)
    +		DebugEmail	Debugging flag (optional)
    +		DataCenter	DataCenter value used in table header (optional)
    +		MinQuality	MinQuality email sending filter (optional)
    +		ShortHeader	Compress header table and leave less whitespace (optional)
    +		StaticMapType	Map type for the google static map (optional)

## 3. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given.

    command arg1				processed by		function

    DataCenter CHAR				config			output

> Optional DataCenter value used in table headers. Value should be enclosed in quotes.

    Debug flag				config			output

> Sets a flag to control the volume of debugging information output by ewhtmlemail. If flag is zero, no debug info is written. If flag is non-zero, debug information is written to the logfile and screen.

>     Default:	0
>     Sample:		Debug 0

    DebugEmail flag				config			output

> Sets a flag to control whether the email command used is logged by ewhtmlemail. If flag is zero, the command is not logged. If flag is non-zero, the command is written to the logfile and screen.

>     Default:	0
>     Sample:		DebugEmail 0

    EmailProgram path_to_email		process_message		processing

> Sets the path to the email program as path_to_email. Note that this path must include the name of the program. Usually set to "/usr/sbin/sendmail" or "blat.exe". If EmailProgram is not specified (commented out), ewhtmlemail will only save html files with the events to the folder defined by HTMLFile.

>     Default:	none
>     Sample:		EmailProgram /usr/sbin/sendmail

    EmailRecipient recipient		process_message		Processing

> Registers one recipient email address with the ewhtmlemail. ewhtmlemail will send every recipient an email message on the detected events. Up to 20 "EmailRecipient" commands may be issued, but none are required. Each recipient address can be up to 60 characters long.

>     Default:	none
>     Sample:		EmailRecipient  jdoe@yourmachine.edu

    GetLogo instID	modID			config			earthworm setup

> Gets event messages (TYPE_HYP2000ARC) originating from the installation and module IDs given by instID and modID, respectively. Each ID is a character string. Valid strings are listed in earthworm.d.

>     Default:	none
>     Sample:		GetLogo  INST_CIVISA  MOD_EQPROC

    HeartBeatInt nsec			config			earthworm setup

> Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by ewhtmlemail.

>     Default:	none
>     Sample:		HeartBeatInt 30

    HTMLFile filename			process_message			Processing

> Base name for the html files generated by ewhtmlemail. The actual filenames will be given by "filename_EventID.html". The term EventID is the event number assigned by binder.

>     Default:	none
>     Sample:		HTMLFile  home/earthworm/events/ew

    InRing ring				config			earthworm setup

> Tells ewhtmlemail which shared memory region to find input events. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. ewhtmlemail will read only TYPE_HYP2000ARC messages.

>     Default:	none
>     Sample:		InRing HYPO_RING

    LogFile switch				config			output

> Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, statmgr will write a daily log file(s) called statmgrxx.log_yymmdd where xx is statmgr's module id (set with "MyModuleId" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).

>     Default:	none
>     Sample:		LogFile 0

    MagWaitSeconds seconds			process_message			Processing

> If UseML and/or UseMW is specified then this command sets the length of time to delay before releasing an email that may (or may not) have an ML or MW magnitude. The time is in seconds.

>     Default:	5
>     Sample:		MagWaitSeconds  200

    MaxMessageSize size			process_message		earthworm setup

> Specifies the maximum size in bytes of the TYPE_HYP2000ARC messages to retrieve from the inRing. Note that HYP2000ARC messages may be very large.

>     Default:	none
>     Sample:		MaxMessageSize  16384

    MAX_SAMPLES nsamp			process_message		earthworm setup

> Specifies the maximum number of samples, nsamp, to retrieve from a WaveServer for any given station.

>     Default:	60000
>     Sample:		MAX_SAMPLES  60000

    MinQuality CHAR				config			output

> Sets a minimum quality level for sending emails. CHAR can be A,B,C, or D. KML or HTML files will still be created but not sent.

    MyModuleId mod_id			config			earthworm setup

> Sets the module id. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number. If more than one ewhtmlemail is running at the same time, they must be given different module ids!

>     Default:	none
>     Sample:		MyModuleId  MOD_EWHTMLEMAIL

    ShortHeader CHAR				config			output

> Optional flag to compress the header table and leave less whitespace.

    site_file filename			process_message			Processing

> Enters site codes and station locations into the site table by reading a HYPOINVERSE format station file called filename. In this file, stations are described by a 5-letter site name, a 2-letter network code and a 3-letter component code. The picker and binder must also be using this station-naming convention. The format of the file is described under "HYPOINVERSE STATION FILE FOR FULL 12-LETTER (S-N-C-L) CHANNEL NAMES".

>     Default:	none
>     Sample:		site_file  cvarg.hinv

    StaticMapType CHAR				config			output

> Optional map type for the google static map. Can be: terrain, satellite, roadmap or hybrid (satellite+roads).

>     Default:	hybrid
>     Sample:		StaticMapType  satellite

    StyleFile filename			process_message			Processing

> Name of the optional cascading style sheet file to be embedded in the output html files. See information on the structure below.

>     Default:	none
>     Sample:		StyleFile  ewhtmlemail.css

    UseBlat 				process_message			Processing

> Specifies that the EmailProgram is blat type, which takes the syntax "blat.exe file -to recipient". Make sure EmailProgram has the absolute path to blat.exe if it is not in your path, but set the EmailProgram entry regardless.

    UseML 				process_message			Processing

> If specified then ewhtmlemail will detect and use 'ML' magnitude messages generated by the localmag module.

    UseMW 				process_message			Processing

> If specified then ewhtmlemail will detect and use 'MW' magnitude messages.

    WaveServer ip:port			process_message			Processing

> IP address and port for a waveserver. A Maximum of 10 waveservers may be specified. ewhtmlemail will try to contact each waveserver in the specified order to retrieve waveforms for the reporting stations.

>     Default:	none
>     Sample:		WaveServer  192.168.0.1:16022

    WSTimeout nsec			process_message			Processing

> WaveServer timeout in seconds

>     Default:	5
>     Sample:		WSTimeout 5

## 4. STYLE FILE FORMAT

Ewhtmlemail allows minimal configuration of the graphical aspects of the generated html files by embedding a cascaded style sheet. As such, standard css rules apply when customizing this file. Not all elements of the generated html are accessible. Particularly, the characteristics of the google map and google charts are currently hardcoded in ewhtmlemail. Nonetheless, the following Classes and IDs are available:

    DataTable
    ID of the table containing the origin details

    alt
    Class of every second row of the data table.

    MapClass
    Class of the image containing the google map.

    WaveTable
    ID of the table containing the waveforms.

    WaveTableTextRowClass
    Class of the rows within the WaveTable that have a text line with the station name.

    WaveTableTraceRowClass
    Class of the rows within the WaveTable that have a waveform. This waveform is represented as an image extracted from google charts API.

The following presents an example css file.

    /*
    Style Sheet for ewhtmlemail

    Currently, the main html ids to consider for the alert email are:
    DataTable -> The initial table with the basic event info
    WaveTable -> The table with all the traces

    This file is embedded in the automatically generated html email as is.
    Make sure that you know what you are doing before changing it.
    */

    #DataTable {
       font-family: Sans-serif;
       font-size: 12;
       border-collapse: collapse;
    }

    #DataTable th {
       background-color: #000060;
       color: #DDDDFF;
    }

    #DataTable tr td {
       background-color: white;
       color: #000060;
    }

    #DataTable tr.alt td {
       background-color: #DDDDFF;
       color: #000060;
    }

    #WaveTable {
       font-family: Sans-serif;
       font-size: 10;
       border: 1px solid black;
       border-collapse: collapse;
    }

    #WaveTable th {
       background-color: #000060;
       color: white;
    }

    #WaveTable tr.WaveTableTextRowClass td {
       background-color: #DDDDFF;
       color: #000060;
    }

    #WaveTable tr.WaveTableTraceRowClass td {
       height: 80px;
       vertical-align: top;
    }

    .TraceClass {
       max-height: 60px;
       height: auto;
       height: 60px;
       max-width: 600px;
       width: auto;
       width: 600px;
    }

Module Index | ewhtmlemail Overview