QuakeWatch Generic Client
(for Version 1.5)



     The QuakeWatch Generic Client
("QWGenericClient") connects to a QWServer, receives messages, and processes them via client-output modules.  The modules may be configured to send messages in various formats and as files written to multiple directories.
     The "conf/QWGenericConfig.xml" file contains the configuration parameters for the program, including the parameters described below and the connection parameters for the client.  See the "QWConnParams.html" file for a description of the QuakeWatch Connection Parameters.

     The following client-output modules are available:

FileClientModule:  Writes received XML messages out to files.
CubeClientModule:  Translates received messages to CUBE format and writes them out to files.
CapClientModule:  Converts received messages to CAP format and transmits them to email or CAP-server recipients.  Note:  This module is obsolete.  The (separate) QWCapOutClient distribution should be used instead.

     The QuakeWatch Generic Client distribution contains the following files:


QWGenericClient.jar - Program "jar" file for the client.
QWCapSupport.jar - Support "jar" file for the CapClientModule.
startClient - Unix script for starting the client.
stopClient - Unix script for stopping the client.
startStopClient - Unix script for starting/stopping the client.
run - Unix script for running the client interactively.
run.bat - Windows batch file for running the client.
conf/QWGenericClientConfig_sample.xml - Sample configuration file for the client.
conf/QWGenericClientConfig_CAPsample.xml - Sample configuration file for the client.
doc/QWGenericClient.html - This documentation file.
doc/QWConnParams.html - Documentation for the "QuakeWatch Connection Parameters".
doc/CUBE.html - Documentation for the CUBE/QDDS format.
test/TestLoginInfoFile.txt - Test file for client-server login authorization.
QWGenericClientSrc.zip - Source code for the client.

     The QuakeWatch Generic Client distribution contains two sample configuration files, "conf/QWGenericClientConfig_sample.xml" (demonstrating 'FileClientModule' and 'CubeClientModule' configurations) and
"conf/QWGenericClientConfig_CAPsample.xml" (demonstrating a 'CapClientModule' configuration).  The first time a QWGenericClient installation is setup, a customized "conf/QWGenericClientConfig.xml" file should be created.

     When using the 'FileClientModule' and the 'CubeClientModule', the program jar file "QWGenericClient.jar" contains all the resources needed to operate
.  When using the 'CapClientModule', the "QWCapSupport.jar" file must be available (in the same directory as the "QWGenericClient.jar" file).

     The CUBE format is used by the QDDS program, for which the following documentation is available:

USGS NEIC Documentation for QDDS:  http://neic.usgs.gov/neis/qdds/
Distribution Site for QDDS (FTP):  ftp://ehzftp.wr.usgs.gov/QDDS
CUBE Format Documentation:  CUBE.html



Generic Client Parameters

     The following parameters are specified in the "<Settings>" element of the "conf/QWGenericClientConfig.xml" configuration file for the QuakeWatch Generic Client (in addition to the QuakeWatch Connection Parameters).

lastMessageFileName = "fileName"
     Specifies the name of the file used to store a copy of the last message received by the client.  When the client starts up, it uses the message data from the file (if found) to request messages from the server that the client has missed.  If this parameter is not specified then the value will default to "qwLastMessage.dat"
.

prependDeclarationFlag = true/false
     This parameter applies to the content of XML-format message files generated by the 'FileClientModule' and the 'CubeClientModule'.  When this parameter is set to 'true', the content of outputted XML-format messages will be preceded by the value of the 'prependDeclarationText' parameter.  If this parameter is not specified then the value will default to 'false' (no prepended text).

prependDeclarationText = "text"
     This parameter applies to the content of XML-format message files generated by the 'FileClientModule' and the 'CubeClientModule'.  When the 'prependDeclarationFlag' parameter is set to 'true', the content of
XML-format outputted messages will be preceded by the value of the this parameter.  If this parameter is not specified then the value will default to "<?xml version=\"1.0\"?>\n" (the standard XML declaration).  Note that to specify this text in the configuration file, the open and close bracket characters must be substituted with "escaped" codes, as follows:  "&lt;?xml version=\"1.0\"?&gt;\n"


Note:  The 'maxServerEventAgeDays' parameter (described in the QuakeWatch Connection Parameters) is not used by this client.
     When the 'CapClientModule' is not in use and the client is run for the first time, historical messages will not be fetched from the server.  If the client has received messages and is stopped and started, any missed messages will be fetched from the server.
     When a 'CapClientModule' is in use and the client is started, historical messages will be fetched from the server (up to the specified age).  This
allows the 'CapClientModule' to use the historical messages when generating its output.



Client Output Modules

     The QuakeWatch Generic Client supports several client-output modules, which are configured via one or more "<ClientModule>" elements in the client configuration file.  Any number of  "<ClientModule>" elements may be specified, and any combination of module types may be included.  Care must be taken to ensure that when multiple modules with log and message-output files are configured, no two modules are sending data to the same output file.

The following attributes of the "<ClientModule>" element are common to all client-output modules.

Name = "moduleName"

     The name associated with the client-output module.


Class = "moduleClassSpec"

     The Java class specification for the client-output module.  This is used to by the program to load the module.  The following table shows the value used for each type of module.  For example, a value of "com.isti.quakewatch.genericclient.FileClientModule" would specify the 'FileClientModule'.

 FileClientModule  com.isti.quakewatch.genericclient.FileClientModule
 CubeClientModule  com.isti.quakewatch.genericclient.CubeClientModule
 CapClientModule  com.isti.quakewatch.genericclient.CapClientModule

LogFileName = "logFileName"
     The log file to be used by the client-output module.
  A date code in the form "_yyyymmdd" will be inserted into the name, and a new log file name will be used each day.  When more than one module is specified, each module must have a separate log file.

LogFileLevel = "level"

     The message level for the module's log file output.  The allowed values are "NO_MSGS", "Error", "Warning", "Info", "Debug", "Debug2", "Debug3", "Debug4", "Debug5" and "ALL_MSGS".  If this attribute is not specified then the value will default to "Error".

ConsoleLevel = "level"

     The message level for the module's console output.  The allowed values are "NO_MSGS", "Error", "Warning", "Info", "Debug", "Debug2", "Debug3", "Debug4", "Debug5" and "ALL_MSGS".  If this attribute is not specified then the value will default to "Error".

ClientModuleSettings:
  Within the ClientModule element may reside a "<ClientModuleSettings>" element containing module-specific settings.  See the client-output module descriptions below for more information on these settings.




FileClientModule

     The FileClientModule outputs received messages to individual files (one file per message).  The following settings may be specified in the "<ClientModuleSettings>" element for the module.

outputMsgFilesDir = "dirname"
     The output directory for message files.  The filenames will be in the form "m###msg.xml", where "###" is the message number for the message.  Additional characters may be added to the filename to make it unique.  When a message is received, it contents are written to a file in the "processMsgFilesDir" directory, and then the file is moved to the "outputMsgFilesDir" directory.  If this parameter is not specified then the value will default to "fileOutData/msgOutput".

processMsgFilesDir = "dirname"
     The process directory for message files.  When a message is received, it contents are written to a file in the "processMsgFilesDir" directory, and then the file is moved to the "outputMsgFilesDir" directory.  If this parameter is not specified then the value will default to "fileOutData/msgProcess".

unpackQWMessageFlag = true/false
     Set 'true' to "unpack" the contents of the "<QWmessage>" element of the received message.  All messages in the QuakeWatch system contain the message data inside of a "<DataMessage>" element surrounded by a "<QWmessage>" element.  If this flag is 'true' then the message data is "unpacked", resulting in the child-elements of the "<QWmessage>" element being written to the message file.  If this parameter is not specified then the value will default to 'false'.  If the "unpackQWMessageFlag" parameter is 'false' then the "unpackDataMessageFlag" and "unpackEQMessageFlag" parameters will be ignored.

unpackDataMessageFlag = true/false
     Set 'true' to "unpack" the contents of the "<DataMessage>" element of the received message.  All messages in the QuakeWatch system contain the message data inside of a "<DataMessage>" element surrounded by a "<QWmessage>" element.  If this flag is 'true' then the message data is "unpacked", resulting in the child-elements of the "<DataMessage>" element being written to the message file.  If this parameter is not specified then the value will default to 'false'.  If the "unpackQWMessageFlag" parameter is 'false' then the "unpackDataMessageFlag" parameter will be ignored.

unpackEQMessageFlag = true/false
     Set 'true' to "unpack" the contents of the "<EQMessage>" element of the received message (if found).  Messages in the ANSS-EQ-XML format will contain an "<Event>" element surrounded by an "<EQMessage>" element.  If this flag is 'true' then the message data is "unpacked", resulting in the "<Event>" element being written to the message file (the other child-elements of the "<EQMessage>" element are not included).  If this parameter is not specified then the value will default to 'false'.  If the "unpackQWMessageFlag" or "unpackDataMessageFlag" parameter is 'false' then the "unpackEQMessageFlag" parameter will be ignored.


xPathFilterExpr = "expression"
     Sets the XPath-syntax filter expression for accepted messages.  If specified then incoming messages will only be accepted if the given expression selects at least one node in the messages.  If not specified (or if set to an empty string) then all messages will be accepted.  See the "XPath-Syntax Filter Expressions" section for more information.


filteredMsgFilesDir = "dirname"
     Sets the name of the output directory for message files that are filtered out via the 'xPathFilterExpr' parameter.  If this parameter is not specified or is set to an empty string then filtered-out messages will be discarded.

prependDeclarationFlag = true/false
     When this parameter is set to 'true', the content of all outputted messages will be preceded by the value of the 'prependDeclarationText' parameter.  If this parameter is not specified then the value will default to 'false' (no prepended text).

prependDeclarationText = "text"
     When the 'prependDeclarationFlag' parameter is set to 'true', the content of all outputted messages will be preceded by the value of the this parameter.  If this parameter is not specified then the value will default to "<?xml version=\"1.0\"?>\n" (the standard XML declaration).  Note that to specify this text in the configuration file, the open and close bracket characters must be substituted with "escaped" codes, as follows:  "&lt;?xml version=\"1.0\"?&gt;\n"




CubeClientModule

     The CubeClientModule converts received messages to CUBE format and outputs them to individual files (one file per message).  This module can be used as a functional equivalent to the QDDS program (operating as a "leaf").  The following settings may be specified in the "<ClientModuleSettings>" element for the module.

outputMsgFilesDir = "dirname"
     The output directory for message files.  The filenames will be in the form "out.#", where "#" is the message number for the message.  Additional characters may be added to the filename to make it unique.  When a message is received, it contents are written to a file in the "processMsgFilesDir" directory, and then the file is moved to the "outputMsgFilesDir" directory.  If this parameter is not specified then the value will default to "cubeOutData/msgOutput".

processMsgFilesDir = "dirname"
     The process directory for message files.  When a message is received, it contents are written to a file in the "processMsgFilesDir" directory, and then the file is moved to the "outputMsgFilesDir" directory.  If this parameter is not specified then the value will default to "fileOutData/msgProcess".

acceptXmlMsgsFlag = true/false
     If 'true' then when non-standard/invalid XML messages are received then they will be written to output-message files (as XML-format text).  If false then the messages will be discarded.  An XML message is considered non-standard/invalid if it does not conform to one of the expected message formats (QuakeML format, ANSS-EQ-XML format or QuakeWatch "QWmessage" format).  If this parameter is not specified then the value will default to 'true'.

acceptNonActualFlag = true/false
     If 'false' then QuakeML and ANSS-EQ-XML-format messages will be ignored if they contain an 'Event' | 'Usage' element set to a value other than "Actual".  If 'true' then all messages will be accepted.  Messages that do not contain an 'Event' | 'Usage' element will always be accepted.  If this parameter is not specified then the value will default to 'false'.

xPathFilterExpr = "expression"
     Sets the XPath-syntax filter expression for accepted messages.  If specified then incoming messages will only be accepted if the given expression selects at least one node in the messages.  If not specified (or if set to an empty string) then all messages will be accepted.  See the "XPath-Syntax Filter Expressions" section for more information.


filteredMsgFilesDir = "dirname"
     Sets the name of the output directory for message files that are filtered out via the 'xPathFilterExpr' parameter.  If this parameter is not specified or is set to an empty string then filtered-out messages will be discarded.

prependDeclarationFlag = true/false
     When this parameter is set to 'true', the content of all outputted messages will be preceded by the value of the 'prependDeclarationText' parameter.  If this parameter is not specified then the value will default to 'false' (no prepended text).

prependDeclarationText = "text"
     When the 'prependDeclarationFlag' parameter is set to 'true', the content of all outputted messages will be preceded by the value of the this parameter.  If this parameter is not specified then the value will default to "<?xml version=\"1.0\"?>\n" (the standard XML declaration).  Note that to specify this text in the configuration file, the open and close bracket characters must be substituted with "escaped" codes, as follows:  "&lt;?xml version=\"1.0\"?&gt;\n"




CapClientModule

Note:  This module is obsolete.  The (separate) QWCapOutClient distribution should be used instead.

     The CapClientModule converts received messages to CAP format and, subject to various user-configurable "alarm" criteria items, sends out CAP-alert and/or email messages to a configurable list of recipients.  When using the 'CapClientModule', the "QWCapSupport.jar" file must be available (in the same directory as the "QWGenericClient.jar" file).  The following settings may be specified in the "<ClientModuleSettings>" element for the module.

maxLoadEventAgeDays = #.#
     Sets the maximum age (in days) for received messages to be retained by the client.  These messages are used by the CapClientModule when generating its output.  When the client is started, historical messages will be fetched from the server (up to the given age).  The age is specified as a floating-point value (which must be greater than zero).  If this parameter is not specified then the value will default to 3.0 days.

localTimeZone = "XXX"
     The "local" time zone to be used in alert messages.  If this parameter is not specified then the value will default to the system default time zone.

emailFromName = "name"
     The "real" name that will appear in the "From:" field of sent alert email messages.  If this parameter is not specified then the value will default to an empty string.

emailFromAddress = "address"
     The email address that will appear in the "From:" field of sent alert email messages.  For the sending of email messages to succeed, this setting must contain a valid email address.  If this parameter is not specified then the value will default to an empty string.

smtpServerAddress = "address"
     The address of the SMTP email server to be used for sending email alert messages.  For the sending of email messages to succeed, this setting must contain the address of an SMTP email server that will accept send-mail requests from the machine on which the program is running.  If this parameter is not specified then the value will default to an empty string.

maxSendMailRetries = ##
     Sets the maximum number of times the program will attempt to send an alert email message after all previous attempts have failed.  If this parameter is not specified then the value will default to 10 retries.

maxSendCapRetries = ##
     The maximum number of times the program will attempt to send a CAP alert message after all previous attempts have failed.  If this parameter is not specified then the value will default to 10 retries.

minCapSeverityDepth = #.#
     The minimum depth to use for the CAP severity detemination.  If this parameter is not specified then the value will default to 0.0.

includeOnlyLargestCircleFlag = true/false
     When set to true only the largest circle will be included in CAP messages.  If this parameter is not specified then the value will default to true.

usQuakesWebStr = "webStr"
     The info/web string for US quakes, not including the actual file name other than the file extension; i.e., "http://earthquake.usgs.gov/recenteqsus/Quakes/.htm".  If this parameter is not specified then the value will default to an empty string and the info/web string will not be included in CAP messages..

wwQuakesWebStr = "webStr"
     The info/web string for worldwide quakes, not including the actual file name other than the file extension; i.e., "http://earthquake.usgs.gov/recenteqsww/Quakes/.htm".  If this parameter is not specified then the value will default to an empty string and the info/web string will not be included in CAP messages.

heartbeatIntervalMSecs = ###
     The amount of time between writing the heartbeat file, in milliseconds (or 0 to disable this feature).  If enabled then the presence of the heartbeat file indicates that the module is running normally.  If this parameter is not specified then the value will default to 0 (disabled).

heartbeatFilename = "filename"
     The name of the heartbeat file.  If this parameter is not specified then the value will default to  "log/CapModuleHeartbeat.txt".
__________
__________

The following parameter items define an earthquake-event filter that may be used to select which events are accepted as being eligible for generating alert messages.  For an event to be accepted, it must satisfy all of the enabled filter items.  Note that if more than one CapClientModule is configured, their filter settings must be identical.

dispMaxAgeDays = ##
     Only earthquake events that are newer than this age (in days) will be accepted.  The age is measured from the event-time for the event and is specified as a floating-point value.  Setting this item to zero will disable it (allowing events of any age to be accepted).  If this parameter is not specified then the value will default to 7 days.

keepDataSources
= "xx"
     This item may contain a comma-separated list of data-source specifiers (i.e. "CI, NC").  If this item is not blank then only earthquake events with matching data-source specifiers will be accepted, and this item will override the "dropDataSources" item.  If this item is blank then earthquake events from all data sources will be accepted (except those dropped via the "dropDataSources" item).  The data-source specifiers are not case-sensitive.  If this parameter is not specified then the value will default to an empty string.

dropDataSources
= "xx"
     This item may contain a comma-separated list of data-source specifiers (i.e. "CI, NC").  If this item is not blank and the "keepDataSources" item is blank then earthquake events with matching data-source specifiers will not be accepted.  If this item is blank then it will have no effect on filtering.  The data-source specifiers are not case-sensitive.  If this parameter is not specified then the value will default to an empty string.

evtMinLatitude
= #.#
     Earthquake events with a latitude less than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "evtMaxLatitude" item are zero then earthquake events of any latitude will be accepted.  If this parameter is not specified then the value will default to 0.

evtMaxLatitude
= #.#
     Earthquake events with a latitude greater than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "evtMinLatitude" item are zero then earthquake events of any latitude will be accepted.  If this parameter is not specified then the value will default to 0.

evtMinLongitude
= #.#
     Earthquake events with a longitude less than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "evtMaxLongitude" item are zero then earthquake events of any longitude will be accepted.  If this parameter is not specified then the value will default to 0.

evtMaxLongitude
= #.#
     Earthquake events with a longitude greater than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "evtMinLongitude" item are zero then earthquake events of any longitude will be accepted.  If this parameter is not specified then the value will default to 0.

dispMinDepth = #.#
     Only earthquake events with a depth (in kilometers) of this item's value or greater will be accepted.  Setting this item to zero will disable it.  If this item is set to a non-zero value and a given earthquake event does not have a depth value then the event will not be accepted.

dispMaxDepth = #.#
     Earthquake events with a depth (in kilometers) greater than this item's value will not be accepted.  Setting this item to zero will disable it.  Earthquake events that do not have a depth value will be unaffected by this item.

dispMaxMagError = #.#
     Earthquake events with a magnitude error greater than this item's value will not be accepted.  Setting this item to zero will disable it.  Earthquake events that do not have a magnitude-error value will be unaffected by this item.

dispMaxHorizError = #.#
     Earthquake events with a horizontal error (in kilometers) greater than this item's value will not be accepted.  Setting this item to zero will disable it.  Earthquake events that do not have a horizontal-error value will be unaffected by this item.

dispMaxVertError = #.#
     Earthquake events with a vertical error (in kilometers) greater than this item's value will not be accepted.  Setting this item to zero will disable it.  Earthquake events that do not have a vertical-error value will be unaffected by this item.

dispMaxStandError = #.#
     Earthquake events with an RMS-time standard error (in seconds) greater than this item's value will not be accepted.  Setting this item to zero will disable it.  Earthquake events that do not have a standard-error value will be unaffected by this item.

dispMaxAzimGap = #.#
     Earthquake events with an azimuthal gap (in degrees) greater than this item's value will not be accepted.  Setting this item to zero will disable it.  Earthquake events that do not have an azimuthal gap value will be unaffected by this item.

dispMinNumPhaUsed = ##
     Only earthquake events where the number of phases is at this item's value or greater will be accepted.  Setting this item to zero will disable it.  If this item is set to a non-zero value and a given earthquake event does not have a number-of-phases value then the event will not be accepted.
__________
__________

The parameter items below are specified in a "<Recipient>" element inside of the "<ClientModuleSettings>" element.  Any number of "<Recipient>" elements may be specified.  Two types of alert recipients are available:  An email recipient will send messages via email.  A CAP recipient will send messages to a CAP server.

recipientName = "name"
     The name to be associated with the alert recipient.  If this parameter is not specified then the value will default to an empty string.

recipientClassName = "classSpec"
     The Java class specification for the alert recipient.  For a CAP recipient the value will be "com.isti.quakewatch.alertcap.AlertCapRecipient".  If this parameter is not specified then the value will default to the class name for an email recipient ("com.isti.quakewatch.alertemail.AlertEmailRecipient").
__________
__________

The following parameter items are used with an email recipient.

emailAddressList = "address(es)"
     One or more email addresses for the recipient.  If this parameter is not specified then the value will default to an empty string.

emailsEnabledFlag = true/false
     When this is set to "false", the recipient will never be sent alert email messages. Otherwise, the recipient is enabled and may be sent alert email messages.  If this parameter is not specified then the value will default to 'false'.

longEmailFormatFlag = true/false
     If not using "CAP" message format ("capMsgFormatFlag"==false) then this determines if the "long" or "short" format is used. When this is set to "false", the alert email messages sent to the recipient will use the "short" format, which provides a concise description (suitable for pagers).  Otherwise, the alert email messages sent to the recipient will use the "long" format, which provides detailed information about the event.  If this parameter is not specified then the value will default to 'true'.

capMsgFormatFlag = true/false
     When this is set to "true", the alert email messages sent to the recipient will use the "CAP" format.  Otherwise, the "short" or "long" format will be used (depending on the "longEmailFormatFlag" value).  If this parameter is not specified then the value will default to 'false'.
____________________

The following parameter items are used with a CAP recipient.

capMsgEnabledFlag = true/false
     When this is set to "false", the recipient will never be sent CAP alert messages.  Otherwise, the recipient is enabled and may be sent CAP alert messages.  If this parameter is not specified then the value will default to 'false'.

servicesURL = "url"
     The services URL for this recipient.  If this parameter is not specified then the value will default to "https://interop.cmiservices.org/axis/services/CAP".

username = "name"
     The username for this recipient.  If this parameter is not specified then the value will default to an empty string.

password = "value"
     The password for this recipient.  If this parameter is not specified then the value will default to an empty string.

postCogIdList = "list"
     The COG ID list for this recipient.  This is a list of comma separated COG IDs to post to or all COGs if this value is an empty string.  If this parameter is not specified then the value will default to an empty string.

maxTransmitTime = ###
     The maximum time (in seconds) for transmitting messages to the recipient.  Setting this value to zero will disable this timeout.  If this parameter is not specified then the value will default to 300 seconds.

pingTime = ##
     The ping time (in minutes) for this recipient (after posting or pinging).  Setting this value to zero will disable periodic pinging.  If this parameter is not specified then the value will default to 5 minutes.

capMsgLogEnabledFlag = true/false
     When set to "true" the CAP alert messages will be logged either to a message file (if "capMsgDir" is not empty) or to the log file for the module.  Otherwise, the CAP alert messages will not be logged.  If this parameter is not specified then the value will default to 'false'.

capMsgDir = "dirname"
     When the logging of CAP messages is enabled ("capMsgLogEnabledFlag"==true), this parameter may be used to specify the directory where the message files (one for each message) will be saved to.  If this is an empty string then the CAP messages will be logged to the log file for the module.  If this parameter is not specified then the value will default to "capMessages".  Note that if there is more than one CAP recipient configured, multiple recipients should not write message files to the same directory.

capMsgMaxAgeDays = ##
     The maximum age (in days) for CAP-message files stored in the recipient's CAP-messages directory (specified via "capMsgDir").   CAP-message files older than this age will be removed from the directory.  If this value is set to zero then no CAP-message files will be removed.  If this parameter is not specified then the value will default to 30 days.

emailAddressList = "address(es)"
     One or more email addresses to receive alert-status messages
when communication to the CAP services fails for any reason or when communication to the CAP services succeeds after a failure, or at program startup.  The communication to the CAP Services may fail due to incorrect service URL or login information, network outage, maintenance on the CAP services server, upgrades to the CAP services program, etc.  Only administrator or operators should have their email addresses in this setting.  If this parameter is not specified then the value will default to an empty string (no alert-status emails sent).
____________________

The following items configure the "alarm" criteria used to determine which events will trigger alert messages for the recipient.  If a received message specifies an earthquake event where all of the configured alarm-crtieria items are satisfied then an alert message will be sent to the recipient.  These items may be used with any type of recipient.

alarmMagnitude = #.#

     The minimum-magnitude criteria value for the alarm.  The magnitude of an earthquake event must be at this value or greater for the alarm to be triggered.  This is a floating-point value.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.  If this parameter is not specified then the value will default to 3.0.

minAlarmDepth = #.#
     The minimum-depth criteria value for the alarm, in kilometers.  The depth of an earthquake event must be at this value or higher for the alarm to be triggered.  This is a floating-point value.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.  If this parameter is not specified then the value will default to 0.0.

maxAlarmDepth = #.#
     The maximum-depth criteria value for the alarm, in kilometers.  If this value is greater than zero then the depth of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will be disabled.  This is a floating-point value.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.  If this parameter is not specified then the value will default to 0.0.

maxAlarmEventHours = #
     The maximum-event-age criteria value for the alarm.  If this value is greater than zero then the number of hours passed since the event-time of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria will be disabled, allowing events of any age to trigger the alarm.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.  If this parameter is not specified then the value will default to 4 hours.

verifiedEventsAlarmFlag = true/false
     When this parameter is set to "true", only "verified" events (those that have been reviewed) will trigger the alarm.  If this parameter is not specified then the value will default to 'false'.

alarmRegions = "regionSpec"
     This parameter may be used to set an optional "region" specification for the alarm.  The value consists of a list of region entries that are separated with a semi-colon (';').  If this parameter is not specified then the value will default to an empty string (no regions).  The following items are available to define an alarm region:

Name of region:  An optional name for the region enclosed in quotes ('\"').

Region data:  The geographical data values for the region, using the following formats:
     For circle regions, the data values consist of a latitude, longitude and radius (in miles) with the following format:  "(lat lon) radius".
     For polygon regions, the data values consist of 3 or more latitude/longitude points with the following format:  "(lat lon)", with each point-entry separated by a comma (',').

Minimum magnitude for alarm:  Sets the minimum-magnitude alarm criteria value for the region.  The magnitude of an earthquake event must be at this value or greater for the alarm to be triggered.  This is a floating-point value enclosed in brackets ('[' and ']').  If this setting is not present or zero then the minimum-magnitude value for the recipient ("alarmMagnitude") will be used.

Note that the format for this parameter is the same as the analogous setting in the CISN Display program.  Regions may be graphically configured in that program, and then the settings value copied over from the configuration file.  The following is an example regions value:

alarmRegions = "\"Poly1\" (-114.8483  34.0833),(-115.1783  34.8167),(-115.2050  33.7667) [2]; \"Circle1\" (-115.2050  33.7667) 5 [3]"




XPath-Syntax Filter Expressions

     The 'xPathFilterExpr' parameter uses XPath-syntax filter expressions to configure a content-based acceptance test for incoming messages.  If the application of the expression to the XML content of a given message results in a match to any elements in the message content then the message will be accepted.  An online XPath tutorial may be found here.

     Below are examples of XPath-syntax filter expressions that may be used.  Note that XPath functions like 'local-name()' and 'namespace-uri()' must be used to successfully process message content with namespaces.

Select a top-level element named "Event" (no namespace):
xPathFilterExpr = "/Event"

Select an element at any level named "Event" (no namespace):
xPathFilterExpr = "//Event"

Select a top-level element named "EQMessage" and matching any namespace:
xPathFilterExpr = "/[local-name()='EQMessage']"

Select an element at any level named "EQMessage" and matching any namespace:
xPathFilterExpr = "//*[local-name()='EQMessage']"

Select an element at any level named "EQMessage" and matching the namespace "http://www.usgs.gov/ansseqmsg":
xPathFilterExpr = "//*[local-name()='EQMessage' and namespace-uri()='http://www.usgs.gov/ansseqmsg']"



8/21/2012 - Eric Thomas, Instrumental Software Technologies, Inc. - info@isti.com