TriNet Network Trigger Request Card Generator `ntrcg'

NOTE: Configuration parameters not know; need sample config file better than
in ntrcg source directory.

Ntrcg receives event signals from tc (trigger coordinator). The context of the
event signal from tc is that a new event with an associated trigger is ready
for processing. Ntrcg queries the database for the event or trigger
information. Then it generates waveform request cards for the appropriate
channels and writes those to the database.

Ntrcg processing happens only upon receipt of signal over CMS connections. 

Throughout this text, `SNCL' will be used to describe a particular data stream
from a particular seismometer instrument. And `channel' will refer to the `C'
part of SNCL, usually the SEED channel name. The term `data stream' will refer
to the two letter character string that make sup the first part of a channel
name; channel direction is the third letter, typically one of E, H or Z. This
terminology should reduce confusion. However, the names of data structures in
ntrcg do not always follow this convention.

On startup, a number of configuration parameters are read and data structures
are set up before processing begins. Lists of `configured' and `active' SNCLs
are read from the database. Configured SMCLs are listed in the config_channel
table as being configured for named programs. A Mapfile (also specified in 
config_channel table) is read in and is used to fill in the
ChannelNameMap. This provides a mapping from data streams (2-letter) to channel
(3-letter) names.

From the list of configured SNCLs, the channel names are mapped into larger
lists of channel names and hence SNCLs. Those SNCLs which are found to be on
the active list are formed into a ChannelSet for the configured SNCL;
these are added to the ChannelMap.

Note that, unlike rcg, ntrcg has no Criteria lists or Windows. That's because
ntrcg can use the channel triggers to select channels for archiving.

On receipt of an Event signal (contains evid only; context is that a subnet
trigger has occured that is not associated with a binder event and thus a
subnet event has been created), ntrcg queries the database to determine if
this machine should generate request cards. If so, it then queries the
database for trigger information for this event. From tables nettrig,
AssocNtE, trig_channel and channel_data, all fields of the NetworkTrigger
object are filled in. The event's preferred magnitude, and all the arrivals
for all events associated with this event's trigger are read from the
database. As currently used, ntrcg will not find an phase arrivals or
magnitudes for this event. In that case, mag = 0 in the below tests.

NOTE: see trig2ps and trig2db to see how the trigger information gets from
carlsubtrig into the database.

If the trigger.all_chans == TRUE {
   fill SelectedList with all configured channels. 
   Request priority is HIGH if mag >= 3.0; 
   else if channel has an arrival or a trigger, priority is MEDIUM; 
   else priority is LOW.
}
else {
   fill SelectedList with triggered channels and their mapped channels.
   If channel was not on our config list, use it anyway, without mapping.
   Request priority is HIGH if mag >= 3.0; else if channel has an actual
   triggered channel, MEDIUM; else channel was an "also selected: channel from
   carlsubtrig, priority is LOW.

   Also select channel if it has an arrival but no trigger.
   Request priority is HIGH if mag >= 3.0; else MEDIUM   
}
Any selection windows that overlap are merged into a single window for that
channel. 

The Selected list is dumped to a log file. All the requests are logged, and
then written to the database waveform_request table for this event. On
successful write to the database, a Request Signal is sent via CMS (contains
evid only).




Major Data Structures
ChannelNameList:	set< string >
ChannelNameMap:		map< string, ChannelNameList >
ChannelMap:		map< Channel, ChannelSet >
ChannelSet:		set< Channel >
Channel:		char *network,
			char *station,
			char *channel,
			double latitude,
			double longitude,
			etc...

NetworkTrigger:		unsigned long trigid,
			char *source,
			char *subsource,
			char *locid,
			char *algorithm,
			TimeStamp trigdate,
			int all_chans,
			TimeWindow savewin,
			TriggerList trigs
TriggerList:		map< Channel, Trigger >
Trigger:		unsigned long trigid,
			trigType trigflag,
			TimeStamp trigtime,
			TimeWindow savewin


SelectedList:		map< Channel, SelectInfo >
SelectInfo:		TimeWindow win,
			requestPrioType priority
TimeWindow:		TimeStamp start, end
RequestList:		list< RequestCard >
RequestCard:		Channel chan,
			TimeWindow win,
			int retry,
			TimeStamp lastretry,
			requestType rtype,
			requestPrioType priority


Major Enumeration Types
requestType:		Unknown, Trig, Cont
requestPrioType:	Unknown, Low, Med, High
trigType:		Unknown, Trig, Member