overlays linear event tables.  OVERLAYEVENTS2 is like ARC OVERLAYEVENTS, but was written because OVERLAYEVENTS sometimes produces erroneous results.



OVERLAYEVENTS2 <out_event_source> {UNION | INTERSECT} {selection_file} {cover} {route_system} {max_overlap} {in_event_source...in_event_source}




<out_event_source> - the LINEAR EVENTSOURCE that identifies the specifications for the output event table that will contain the results of the overlay.


This output table must not already exist.


{UNION | INTERSECT} - which overlay operation to perform.


UNION - The output event table is the union of all input events.  This is the default.


INTERSECT - The output event table is just the intersection of all input events.  In other words, only where all input events overlap are output events created.


{selection_file} - a file created by ARCPLOT WRITESELECT that contains the selected set(s) that are to be in effect when the input events are overlaid.


This option allows you to overlay only selected events or events on selected routes.  In the latter option the route system for which the events are defined is specified using the {cover} and {route_system} arguments.


If no {selection_file} is specified, then all events are overlaid.


{cover} - the arc coverage that contains the {route_system} for which the events are defined.


This option is used in conjunction with the {selection_file} and {route_system} to select which events are to be overlaid.


{route_system} - the route system within the {cover} for which the events are defined.


This option is used in conjunction with the {selection_file} and {cover} arguments to select which events are to be overlaid.


{max_overlap} - the maximum number of events that may overlap each other in the output table.  When this limit has been reached a warning is displayed and no more events are output for this stretch of route.  The default is 99.


EXPLANATION: For a given stretch of route, if there is no more than one event within each input event table, then there will only be one event in the output table.  However, if there is more than one event within any input event table, then the number of output events grows exponentially, one for each combination of input events.


For instance, if there are two input tables, FISH_SPECIES and SURVEY_ID, and each table has two entries for a stretch of stream, then there will be 2 x 2, or 4 output events.  This isn't so bad, but when there are many input tables, it can be problematic.  For instance, if there are 20 input tables and each has two entries (suppose that they were accidentally duplicated), then there will be 2 to the 20th power, or 1,048,576 output events.


The {max_overlap} argument was added to prevent OVERLAYEVENTS2 from getting stuck in a virtually infinite loop.  In the above example, if the default {max_overlap} of 99 is used, then only 99 out of the 1+ million combinations are output, a warning is displayed, and then the program moves to the next stretch of stream.


{in_event_source...in_event_source} - the input LINEAR EVENTSOURCEs that define the event tables to be overlaid.


If none are specified, the user is prompted for the event source names.





OVERLAYEVENTS2 runs from the ARC module of ARC/INFO 7x.


OVERLAYEVENTS2 uses many other AMLs and a JAVA program.  The AMLs need to reside in a directory in your &AMLPATH and &MENUPATH, and the JAVA class files need to reside in a directory in your CLASSPATH environment variable.  For more information, see overlayevents2.readme.







1) To display usage:


Arc: &run overlayevents2 usage

Usage: OVERLAYEVENTS2 <out_event_source> {UNION | INTERSECT} {selection_file} {cover} {route_system} {max_overlap} {in_event_source...in_event_source}


2) In this example OVERLAYEVENTS2 is used to find the intersection of three event tables:


Arc: &run overlayevents2 out_eso intersect # # # # fish_eso class_eso ~ flow_eso