Syntax

   FACTORY_DEF <ReaderKeyword> ElementFactory
   [FACTORY_NAME <factory name>]
   [INPUT FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]*
   LIST_NAME <list name>{}
   [ELEMENT_NUMBER_FIELD <field name>]
   [BASE_NUMBER_LIST_FIELD <field name>]
   [CLONE_GEOMETRY [YES|NO]]
   [ATTR_ACCUM_MODE (HANDLE_CONFLICT|PREFIX_INCOMING|INCOMING_ONLY)]
   [ATTR_CONFLICT_RES (ORIGINAL_IF_CONFLICT|INCOMING_IF_CONFLICT)]
   [CLIPPER_PREFIX <attribute prefix value>]
   [MODE (ANTIQUE|CLASSIC|LEAN|LEAN_AND_MEAN)]
   [OUTPUT (BASE|ELEMENT|NOLIST)
      FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]*

Overview

   This factory takes a feature with a list identified by <list name> and
   returns one feature for each element in that list, as well as the original
   feature. The list elements are returned without geometry on them unless the
   CLONE_GEOMETRY clause is specified in the factory definition.

   When CLONE_GEOMETRY is specified with no arguments, or with YES as its
   argument, each element feature has the geometry of the original feature. In
   this case, an attribute named ElementFactory.baseCloned is added to each
   feature output from the factory via the BASE output tag. If the output BASE
   feature has been cloned, then it will have the value of TRUE, otherwise the
   value will be FALSE.

   If BASE_NUMBER_LIST_FIELD is specified, then this is taken to indicate the
   name of a list attribute that should be added to the BASE feature that is
   output. This list attribute will contain all the element numbers that were
   created from this feature, in order. This attribute may be useful in
   rejoining the elements later in a ReferenceFactory or through some other
   method.

   The original feature is output if the BASE output tag is specified. If the
   ELEMENT_NUMBER_FIELD is specified, then each element feature output is given
   an attribute containing the element's list position.

   This factory merges attributes between the original feature and attributes
   coming from the list. The merging is based on the 3 parameters,
   ATTR_ACCUM_MODE, ATTR_CONFLICT_RES, and CLIPPER_PREFIX. The merging may
   take the original or incoming attributes, possibly prefixed, based on
   the combinations of these various parameters.

   The MODE directive allows you to fine-tune the type of attriubutes that will
   appear on the elements that are created. This is especially useful in
   improving efficiency when extremely large lists are being split apart. If no
   MODE is specified, the CLASSIC mode is used as the default.

      Tip: The @XValue, @YValue, and @ZValue functions can be used to supply
      coordinates to element point features.

   CLASSIC Mode

      The list elements that are produced in CLASSIC mode will retain all the
      attributes of the original BASE feature. In addition, all of the
      attributes of each particular element in the list will be added without
      the list prefix.

   ANTIQUE Mode

      This will produce the same output as CLASSIC, but it will be using the
      original, slower code. This should not ever be necessary.

   LEAN Mode

      The list elements that are produced in LEAN mode will retain all the
      attributes of the original BASE feature except for the list attributes
      referred to in the LIST_NAME clause. In addition, all of the attributes of
      each particular element in the list will be added without the list prefix.

   LEAN_AND_MEAN Mode

      The list elements that are produced in LEAN_AND_MEAN mode will not retain
      any of the attributes of the original BASE. They will only add the
      attributes of each particular element in the list, without the list
      prefix. When the lists have large numbers of elements, using this mode
      will significantly speed up performance.

   Example:

   Suppose we have a BASE feature with the following 6 attributes. (The
   LIST_NAME used here would be "ID{}".)

      Name
      Type
      ID{0}.dec
      ID{0}.hex
      ID{1}.dec
      ID{1}.hex

   The directive MODE CLASSIC will produce elements with 8 attributes:

      Name
      Type
      dec
      hex
      ID{0}.dec
      ID{0}.hex
      ID{1}.dec
      ID{1}.hex

   The directive MODE LEAN will produce elements with 4 attributes:

      Name
      Type
      dec
      hex

   The directive MODE LEAN_AND_MEAN will produce elements with 2 attributes:

      dec
      hex

   In terms of speed, here is the order to expect, in a "general" case, from
   fastest to slowest:

      LEAN_AND_MEAN
      LEAN
      CLASSIC
      ANTIQUE

   Of course, specific types of data will make this order change, as each
   technique works differently on specific types of features. Note that LEAN
   will sometimes be slower than CLASSIC because it basically does the same
   thing as CLASSIC with the addition of some RemoveAttribute calls (requiring
   an iteration through all the attributes). In other cases LEAN will be faster
   because it doesn't call the cloneAttributes function when a feature is just
   loaded with attributes.

Output Tags

   The ElementFactory supports the following output tags.

   BASE

      The original feature.

   ELEMENT

      A single feature for each element in the list.

         The attributes present on this feature are based on the BASE feature
         and depend on the MODE being used.

         These features have no geometry unless the CLONE_GEOMETRY clause is
         specified in the factory definition.

         The feature may have an additional field indicating its position in the
         original list.

   NOLIST

      The original feature, if it did not contain the specified list.