Earthworm Modules:
CarlSubTrig Configuration File

(last revised 8 Feb 1999)
Page Index:
1. Functional command listing
2. Alphabetic command listing & description

On startup, CarlSubTrig reads the configuration file named on the command line. Commands in this file set all the parameters used for performing the subnet logic for the Carl Johnson trigger system. In the control file, lines may begin with a valid carlsubtrig 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: @model.d).
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

1. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by carlsubtrig, grouped by the function they influence. All of the commands are required except Debug; they may be specified in any order in the control file.

	Earthworm system setup:
		MyModuleId		required
		RingNameIn		required
		RingNameOut		required
		HeartBeartInterval	required
		Debug
		GetEventsFrom		required

	Station parameters:
		StationFile		required
		Latency			required
		DefStationDur		required

	Subnet trigger parameters:
		NetTriggerDur		required
		SubnetContrib		required
		PreEventTime		required
		MaxDuration		required
		Subnet			required

	Trigger message parameters:
		ListSubnets		optional
		AllSubnets		optional
		CompAsWild		optional
		Channels		optional

2. 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. Default values and the values used by PNSN are listed after each command description.


command arg1			processed by		function

AllSubnets nsubnets		ReadConfig		Earthworm setup 
		
If nsubnets trigger for an event, then the trigger message will include the SCN wildcard. A process reading the trigger message could understand this wildcard to mean "retrieve data for All stations".

Default:  0
Example:  AllSubnets  10

Channel SCN			ReadConfig		Earthworm setup 
		
Specify a single SCN that should be listed in all trigger messages. For example, this can be used to list time channels that never trigger but should always be present in waveform data filesets. This command can be used as many times as necessary.

Default:  0
Example:  Channel WWVB.TIM.UW

CompAsWild			ReadConfig		Earthworm setup 
		
Flag with no value. If present, carlsubtrig will put the wildcard `*' in the trigger message in place of component names. This can be used if you have multi-component stations but only want to listen for station triggers from the vertical component.

Default:  0  (flag not set)
Example:  CompAsWild

Debug level			ReadConfig		Earthworm setup 
		
Sets the debug logging level for CarlSubTrig. With level set to zero minimal logging is done. Very verbose logging is obtained with level set to 4.

Default:  0
Example:  Debug  3

DefStationDur nsecs		ReadConfig		Station parameters
 		
Sets the default station trigger duration to nsecs seconds. This value is used to terminate a station trigger only if no trigger-off message matching a trigger-on message is received from CarlStaTrig.

Default:  none
Example:  DefStationDur  120

GetEventsFrom inst mod_id	ReadConfig		Earthworm setup
 		
Contrls the TYPE_CARLSTATRIG messages input to carlsubtrig. CarlSubTrig will only process TYPE_CARLSTATRIG messages that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.h/earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Only one "GetSumFrom" command may be issued; wildcards (INST_WILDCARD and MOD_WILDCARD) will force carlsubtrig to process all station trigger messages, regardless of their place of origin.

Default:  none
Example   GetEventsFrom  INST_WILDCARD  MOD_WILDCARD

HeartBeatInterval nsec		ReadConfig		Earthworm setup
		
Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by carlsubtrig.

Default:  none
Example:  HeartBeatInterval 30

Latency	nsec			ReadConfig		Station parameters
 		
Specifies the number of seconds that carlsubtrig will wait for delivery of station trigger messages. This allows for slow telemetry paths and other delays.

Default:  none
Example:  Latency   15

ListSubnets ls		ReadConfig		Earthworm setup 
		
Flag for determining how which SCNs will be listed in the trigger message. When ListSubnets is absent or ls is 0, the trigger message will include all triggered SCNs. If ls is 1, the trigger list will include the untriggered SCNs as well as the triggered SCNs from the triggered subnets (but will omit triggered SCNs that are NOT in the triggered subnets). When ListSubnets is 2, the trigger message will list all SCNs from the triggered subnets, as well as all other triggered SCNs (union of options 0 and 1). When ListSubnets is 3, the trigger message will list all SCNs in any subnets that have at least one triggered SCN. However, if more than AllSubnets have triggered, then the SCN wildcard will be listed instead of a long list of non-triggered stations. If this flag is absent, then carlsubtrig lists only stations that actually triggered during the event.

The idea here is to adjust the number of SCNs in the trigger message for a small event. With ListSubnets at 1, we include untriggered SCNs from triggered subnets. If the subnets are layed out in small geographic areas, then we might expect to have some seismic signal from all SCNs in triggered subnets. By including those SCNs in the trigger message, we allow downstream analysis to have the opportunity to look at the data from those SCNs. If we increase ls to 3, then we are being more conservative in that we save data for anything in subnets that had any SCNs trigger. In practice, we find that this high value results in almost every SCN being listed. This is particularly true when there is a lot of weather or telemetry noise present on the network.


Default:  0  (flag not set)
Example:  ListSubnets  1

MaxDuration nsec		ReadConfig		Subnet parameters
 		
Specifies the maximum duration of a network trigger as nsec seconds. This could be used to limit the size of datafiles retrieved from a wave server.

Default:  none
Example:  MaxDuration  1800

MyModuleId mod_id		ReadConfig		Earthworm setup
		
Sets the module id for labeling all outgoing trigger, heartbeat, and error messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates to a unique single-byte number.

Default:  none
Example:  MyModuleId MOD_CARLSUBTRIG

NetTriggerDur nsecs		ReadConfig		Subnet parameters
 		
Sets the base network trigger duration to mod_id seconds. The minimum trigger duration is the sum of PreEventTime, NetTriggerDur and SubnetContrib times the number of subnets that triggered.

Default:  none
Example:  NetTriggerDur  10

PreEventTime nsecs		ReadConfig		Subnet parameters
		
Specifies the number of seconds nsecs before the initial station trigger to start the network trigger. This can be used to start saving waveform data prior to the first phase arrivals. The minimum trigger duration is the sum of PreEventTime, NetTriggerDur and SubnetContrib times the number of subnets that triggered.

Default:  none
Example:  PreEventTime  10

RingNameIn ring			ReadConfig		Earthworm setup
		
Tells carlsubtrig which shared memory region to use for input. 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.

Default:  none
Example:  RingNameIn  PICK_RING

RingNameOut ring		ReadConfig		Earthworm setup
		
Tells carlsubtrig which shared memory region to use for output. 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.

Default:  none
Example:  RingNameOut HYPO_RING

StationFile sta_file		ReadConfig		Station parameters
		
Specifes sta_file as the file of stations to be monitored by carlsubtrig. This file can be the same station file as the one for CarlStaTrig. This file must list all the stations that make up the Subnets. This file lists each station by station name, component and network. It also specifies the Trigger Time To Live. This is the number of seconds that each station trigger will be help active in CarlSubTrig after CarlStaTrig reports the station trigger off. This Trigger Time To Live allows for the seismic signal propagation time from each station to the other stations in the subnet.

Default:  none
Example:  StationFile  pnsn_trig.sta


Sample Station File

#
#   carlsta/subtrig.sta  FOR PNSN
#
#   PNSN station list
#
# Arbitrary Station Component Network Trigger
#           Code    Code      Code    Time To Live
# --------- ------- ------- --------- ------------
  station   GMW	    EHZ	    UW        10
  station   GSM     EHZ	    UW        10
  station   BLN     EHZ	    UW        10
  station   CPW     EHZ     UW        10
  station   JCW     EHZ     UW        10

Subnet code ntrig sta.comp.net ...	ReadSubnet	Subnet parameters
 		
This command lists the subnet code, number of stations ntrig required to trigger the subnet, and the list of stations making up the subnet. Code is a string (up to 3 characters) that is used to identify the subnet in logged messages. There may be any number of Subnet commands, and there may be up to 20 stations in one subnet.

Default:  none
Examples: Subnet 2   4   LO2.EHZ.UW FMW.EHZ.UW RER.EHZ.UW RCM.EHZ.UW RCS.EHZ.UW
          Subnet RG  3   MLK.VHZ.NC MEM.VHZ.NC MSL.VHZ.NC MCS.VHZ.NC MCM.VHZ.NC 

SubnetContrib nsecs		ReadConfig		Subnet parameters
 		
Specifies the number of seconds nsecs that each triggered subnet contributes to the total duration of the network trigger. The minimum trigger duration is the sum of
PreEventTime, NetTriggerDur and SubnetContrib times the number of subnets that triggered.

Default:  none
Example:  SubnetContrib   15

Module Index | CarlStaTrig/CarlSubTrig Overview | CarlStaTrig Commands

The URL of this page is [http://www.cnss.org/EWAB/cmd/carlstatrig.html]
Contact: lombard@geophys.washington.edu