TriNet Request Card Generator `rcg'

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

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

Rcg processing happens only upon receipt of signal over SmartSocket
connections. 

Throughout this text, `SNC' (soon to be SNCL) will be used to describe a
particular data stream from a particular seismometer instrument. And `channel'
will refer to the `C' part of SNC, 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 rcg 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' SNCs
are read from the database. Configured SCNs are listed in the config_channel
table as being configured for named programs. Active SCNs are listed in the
channel_data table as being usable for a given time period. A Mapfile
(specified in config file) is read in and is used to fill in the
ChannelNameMap. (No sample is provided in the source directory. It appears
that this provides a mapping from data streams (2-letter) to channel
(3-letter) names.)

From the list of configured SNCs (perhaps these have only two-letter channel
names here?) the channel names are mapped into larger lists of channel names
and hence SNCs. Those SNCs which are found to be on the active list are formed
into a ChannelSet that for the configured SNC; these are added to the
ChannelMap.

Next, for each configured SNC, a criteria file is read in (file name was read
from config_channel table above). The criteria file lists Criteria parameters
for one or more data streams. The file is parsed into a Criteria structure
which gets mapped to the configured SNC in the CriteriaMap. There may be one
or more Criteria structures for a configured SNCs; there will always be a
default Criteria for each configured SNC. Part of Criteria data read from file
are the Window calculation parameters Scalar, Distweight, Magweight, Maxdur.

On receipt of an Event signal (contains evid only), rcg queries the database
to determine if this machine should generate request cards. If so, it then
gets Event information for this evid and the configured SearchNet (Auth
code). Event info includes preferred origin, its arrivals, and the preferred
magnitude. For each arrival, a selection TimeWindow is set: start time is
arrival time - picktimestart; end time is arrival time + picktimeend. If event
mag >= 3.0, request priority is High; other it is Medium. Selection window is
added to SelectedList for the SNC. Overlapping windows are merged to produce a
single window for an SNC.

In addition to the Arrival SNCs, all the SNCs in the channel map are
considered. If an SNC's Criteria is satisfied for this event, it will have a
TimeWindow set for it. Selection criteria are one or more of Mag range (event
mag between a min and max magnitude); Distance range (station - hypocenter
distance within min and max distance); Depth range (event depth between min
and max depth); magnitude-distance test: 
(mag - minmag) / (maxmag - minmag) >= (dist - mindist) / (maxdist - mindist) 
A given SNC can be configured to use any combination of these tests; if any
configured test fails, the SNC is not selected by that Criteria. For selected
SNCs, the TimeWindow is computed: start = origin time + P arrival time - Start
parameter; end = window start + smaller of (Scalar + (Distweight * distdeg) +
0.5 + (Magweight * pow(10.0, ((-2.46 + mag) / 2.82)))) and Maxdur.
Selected SNCs here are added to the SelectedList; overlapping windows are
again merged to single windows. For events with mag >= 3.0, priority is High;
otherwise it is Low.

For all SNCs in SelectedList, SNCs in ChannelNameMap are expanded into their
mapped SNC lists; these additional SNCs are added to SelectedList.

The Selected list is dumped to a log file. Then RequestCard structures are
filled for each SNC; the request type is set to Trig. 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
SmartSocket (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...
CriteriaInfoList:	list< CriteriaInfo >
CriteriaMap:		multimap< Channel, CriteriaInfoList >
CriteriaInfo:		Criteria crit,
			WindowCalculator wincalc
Criteria:		int valid,
			char *seedstream,
			double minmag, maxmag,
			double mindist, maxdist,
			double mindepth, maxdepth,
			int critset,
			int usemagdist
WindowCalculator:	int start,
			int scalar,
			int maxdur,
			double distweight,
			double magweight
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