tc (trigger coordinator)
LAST UPDATED ON
Dec 2, 2009
NAME
tc
STATUS
ACTIVE
PURPOSE
tc is an abbreviation for trigger coordinator and its job is to resolve coincident subnet triggers and events. Tc launches CMS messages to the appropriate request card generator program which will write waveform requests for an event based trigger (hypoinverse) or subnet trigger (carlsubtrig). It also writes into the event table a "st" type event for subnet triggered only events. Tc is initiated by a CMS message from the trig2db module (Subnet Trigger Id into nettrig table) or from the ec module (Event Id into event table).
If there is only an event (no subnet trigger coincident), then the tc module issues a UnassocEvent CMS message. If there is ONLY a subnet trigger then the module will write an origin entry for the event and set the etype to "st" for Subnet Trigger and then send the UnassocTrigger CMS message. If there is a coincident event and subnet trigger, then the subnet trigger is associated with the event via the assocnte database table and the AssocEvent CMS signal is sent. The assocnte database table links the subnet trigger table nettrig with the event for which an association was made.
Gory details from Pete Lombard's analysis:
On event signal arrival:
Get Event info from database
For all known EventAssocs in state Trig_Only, find first event for which
this new event falls within the TimeWindow "matchtime".
if found, associate new event with this trigger: {
Remove EventAssoc from EventList
Set tc wakeuptime to that of first EventAssoc on EventList
Write association to database in AssocNtE table (evid, trigid, auth,
subsource, wfflag = TRUE).
Send AssocEvent signal.
For each EventAssoc in state Event_Only, find ones "contained" in this
trigger. Contained means an event origin time falls within the
EventAssoc's TimeWindow "conttime"
If found {
Remove this event from EventList
Set tc wakeuptime to that of first EventAssoc on EventList
Write association to database in AssocNtE table (evid, trigid,
auth, subsource, wfflag = FALSE).
no AssocEvent signal needed; it has already been sent(?)
}
}
else {
Create new EventAssoc structure for this event.
Set EventAssoc curstate = Event_Only
set EventAssoc timeout = origin time + MaxTrigDuration + MaxProcDuration
Insert (timeout, EventAssoc) pair into EventList
Set tc wakeuptime to that of first EventAssoc on EventList
}
On trigger signal arrival:
Get Trigger info from database NetTrig and trig_channel tables
Set matchtime TimeWindow: start is earliest station trigger start -
PreTrigBuf; end is earlier of latest station window end, matchtime.start + AssocDur
Set conttime TimeWindow: start is earliest station trigger start -
PreTrigBuf; end is latest station window end time.
For all events in state Event_Only, find events that fall within this
trigger's matchtime window.
If found {
Pull EventAssoc from EventList
Set tc wakeuptime to that of first EventAssoc on EventList
Write association to database in AssocNtE table (evid, trigid, auth,
subsource, wfflag = TRUE).
Send AssocEvent signal.
For each EventAssoc in state Event_Only, find ones "contained" in this
trigger. Contained means an event origin time falls within the
EventAssoc's TimeWindow "conttime"
If found {
Remove this event from EventList
Set tc wakeuptime to that of first EventAssoc on EventList
Write association to database in AssocNtE table (evid, trigid, auth,
subsource, wfflag = FALSE).
no AssocEvent signal needed; it has already been sent(?)
}
}
else {
Create new EventAssoc structure for this trigger.
Set EventAssoc curstate = Trig_Only
set EventAssoc timeout = subnet trigger time + AssocDur + EcFinalDur +
MaxProcDur
Insert (timeout, EventAssoc) pair into EventList
Set tc wakeuptime to that of first EventAssoc on EventList
}
On EventAssoc timeout:
Remove EventAssoc from EventList
switch (curstate) { no "drop-through" from one case to next.
Trig_Only:
Create event for this trigger {
Set Origin.locevid = trigger ID
Set Origin.timedate = trigger time
Set Origin location to bogus
Get new evid from database sequence
Write event info to database tables Event, Origin
Write association to database in AssocNtE table (evid, trigid, auth,
subsource, wfflag = TRUE).
Send UnassocTrig signal.
For each EventAssoc in state Event_Only, find ones "contained" in this
trigger. Contained means an event origin time falls within the
EventAssoc's TimeWindow "conttime"
If found {
Remove this event from EventList
Set tc wakeuptime to that of first EventAssoc on EventList
Write association to database in AssocNtE table (evid, trigid, auth,
subsource, wfflag = FALSE).
no AssocEvent signal needed; it has already been sent(?)
}
}
Event_Only:
Send UnassocEvent Signal (event not associated with a trigger)
}
HOW TO RUN
tc is run using the following command line:
tc tc.cfg
where the tc.cfg is described below.
CONFIGURATION FILES
tc.cfg has the following arguments:
- Logfile path_with_prefix - the path with a logfile prefix where daily logs will be stored.
- LoggingLevel n - Set the level of logging the program will do. 0 = off, higher numbers are more verbosity.
- ProgramName TRIG_COORD - the unique name to allow this module to connect to CMS and be identifed.
- CMSConfig cms.cfg - Points to the cms configuration file which holds all CMS details. In addition, the common CMS signals should be in the config file.
- AssociationDuration time_in_secs - the number of seconds in which to associate an event with a subnet trigger.
- MaxTrigDuration time_in_secs - the number of seconds to retain a subnet trigger in memory before releasing it that no matches showed up (30 min at Caltech).
- ECFinalDuration time_in_secs - the time it takes in seconds from origin time till the event coordinator releases the CMS signal for an event.
- MaxProcDuration time_in_secs - the time it takes in seconds for any processes on an event to finish. This is added to the MaxTrigDuration and PreTriggerBuffer and the ECFinalDuration to create the end time of the subnet to event association matching.
- PreTriggerBuffer time_in_secs - This is how many seconds before a subnet trigger to include in an event match.
- TriggerSubject signal_name - the name of the CMS signal to use for notification of Subnet Triggers (sent from trig2db).
- EventSubject signal_name - the name of the CMS signal to use for notification of Events (sent from trimag or ec as is done in NC).
- AssocEventSubject signal_name - the name of the CMS signal to use for events that have subnet triggers (usually received by ntrcg).
- UnassocEventSubject signal_name - the name of the CMS signal to use for events that have no subnet triggers (usually received by rcg).
- HeartbeatSubject signal_name - the heartbeat CMS signal that the module writes (note this is not used by any CMS receiver yet but is required).
- UnassocTrigSubject signal_name - the name of an unassociated trigger signal to be sent when a subnet trigger has no matching event (OPTIONAL).
- Auth authority - the 2 character network code of the authority running the tc module (e.g., CI, NC, BK, HI etc).
- Subsource source - the RT host number of the host running TC so that different TC decisions can be attributed to different RT hosts.
- HSInterval n - how often in seconds to send a heartbeat signal to CMS.
- DBService dbname - the name of the database being used (for most this will be rtdb or rtdb2 or archdb)
- DBUser username - the name of the database user account (for most this will be rtem)
- DBPasswd password - the password for the database user account specified by DBUser
An example configuration file used on the Caltech test system is shown below:
# # General configuration parameters # CMSConfig ../cms/conf/cms.cfg Include ../cms/conf/common_signals.cfg Logfile ../rt/logs/tc LockFile ../rt/locks/tc.lock LoggingLevel 2 ProgramName TRIGCOORD HSInterval 30 # # Application configuration parameters # TriggerSubject /signals/trig2db/trigger EventSubject /signals/trimag/magnitude AssocEventSubject /signals/trigcoord/event/assoc UnassocEventSubject /signals/trigcoord/event/unassoc AssocDuration 90 MaxTrigDuration 1800 ECFinalDuration 90 MaxProcDuration 15 PreTriggerBuffer 15 # db related settings Include ../db/db_info.d Include ../db/db_source.d
where db_source.d contains:
# this is a commonly used fields in RT programs # # to define the authority (netcode) for the program Auth CI #to define the subsource field in the database when writing data for a program Subsource RT4
DEPENDENCIES
The tc module depends on CMS being running and the Oracle Database being available and populated with the event and/or subnet trigger (nettrig) to be taken action on. Furthermore, the trig_channel table list of channels must match currently configured channels in the channel_data table. If there is no match from the trig_channel to channel_data table join, then there will be an error message in the tc log stating that there are NO STATION TRIGGERS found for a given trigid. This message is slightly misleading if you are unaware of the join being performed.
The triggers that tc ultimately handles get translated from the carlsubtrig earthworm module and it is critical that the CompAsWild flag NOT be set in the carlsubtrig.d configuration file. If it is set, then the trig_channel.seedchan field will have an asterisk in it and fail to do joins.
Since it receives CMS signals from trig2db and ec, both of those programs must be operating as well.
MAINTENANCE
No specific advice on tc. One thing to note is that if CompAsWild? is used in the carlsubtrig, then tc will not work since this does not work in a SQL query that joins with the channel_data table.
AUTHORS
Patrick Small, Kalpesh Solanki, Peter Lombard
BUG REPORTING
Send bugs to the cisn software working group mailing list and enter them into trac!
