Syntax

   FACTORY_DEF <ReaderKeyword> CorrelationFactory
   [FACTORY_NAME <factory name>]
   [INPUT FEATURE_TYPE <feature type>
   [<attribute name> <attribute value>]*
   [<feature function> ]*]*
   TABLE_DEF (ASCII|CAT|SCAT|CSV|DBF|DATABASE)
   [<attrname> <attrtype>]+
   TABLE_LOCATION <filename>
   [TABLE_ID <tableId>]
   [CORRELATION_SPEC <column name><value>]+
   [OUTPUT_FEATURE_TYPE_COLUMN <column name>]
   [CORRELATION_COLUMNS <input attrname column name>
   <output attrname column name>
   [<default attribute value column name>]]+
   [OUTPUT (CORRELATED|NOT_CORRELATED)
   FEATURE_TYPE <feature type>
   [<attribute name> <attribute value>]*
   [<feature function>]*]*

Overview

   This factory is used to perform correlation operations on features. It takes 
   features and manipulates the attributes based on the directions stored in an 
   associated database table. The table contains instructions on which 
   attributes should be added and possibly which features should be cloned. 
   Effective use of this factory eliminates the need for complex correlation 
   lines in the mapping file. Combinations of the following operations can be 
   performed on features through this factory:
   
   Duplicate attribute  
   
      Specifying input and output attribute names in the columns defined on the 
      CORRELATION_COLUMNS clause duplicates the attribute present on a feature. 
      A default value may be given if the attribute is not present. The result 
      is that the output attribute name will be added to the feature with the 
      value the named input attribute has.

   Add attribute  
   
      Specifying an output but no input attribute name in the columns defined on 
      the CORRELATION_COLUMNS clause adds the new attribute to a feature. The 
      value may be specified by defining a default.

   Remove attribute  
   
      Specifying an input but no output attribute name in the columns defined on 
      the CORRELATION_COLUMNS clause removes the attribute from the feature.

   Change Feature Type  
   
      Specifying a new feature type in the column defined by the 
      OUTPUT_FEATURE_TYPE_COLUMN clause alters the feature type of the output 
      feature.

   Duplicate Feature 
   
      Specifying several new feature types (on different rows) in the column 
      defined by the OUTPUT_FEATURE_TYPE_COLUMN clause causes several copies of 
      each input feature to be output; one for each new feature type.
   
   Every feature that enters this factory exits via one of the output clauses, 
   if specified, in some form. The geometry of all features is left untouched.
   
   The first keyword on the TABLE_DEF clause defines the table type. If the 
   table type is DATABASE, then the TABLE_LOCATION is interpreted as the 
   database ID - either an ODBC data source or an Oracle instance. For file-
   based types, the TABLE_LOCATION is the full path name of the file. 
   
   For more information on specifying a database ID, see the DATASET keyword 
   usage in the Database Reader chapter of the FME Readers and Writers manual.
   
   Further <attrname> and <attrType> settings on the TABLE_DEF clause define the 
   names and types of fields defined in the table. These additional settings are 
   not needed if the table type is either DBF or DATABASE. Some special table 
   settings may be defined here as well depending on the table type. 
   
   If you want specifics on the field types and special fields for each table 
   type, see the discussion under the heading DEF in the FME Readers and Writers 
   manual in the chapter titled Relational Table Reader/Writer.
   
   The TABLE_ID keyword is only needed when reading from a table of the DATABASE 
   type. It is the name of the table in the database.
   
   Keywords <column name> identify table columns.
   
   This factory uses the database table identified in the TABLE_LOCATION clause 
   and finds rows that match the feature. A row is considered to match a feature 
   if all CORRELATION_SPEC clauses match for that feature. 
   
   The CORRELATION_SPEC clause determines which table rows match each input 
   feature. Once matches are made, each table row dictates the actions that will 
   be performed on the feature. A CORRELATION_SPEC is considered to match a row 
   to a feature if the value stored in the <column name> column of the row 
   matches the value of <value>. The value of <value> may be either a literal 
   constant value, for example river; an attribute name preceded by the value-of 
   operator, for example &color; or an attribute function, for example 
   @FeatureType(). If it's an attribute value function, the function will be 
   executed on the current feature and the result will be used for the matching 
   row.
   
   If no matching rows are found, the feature will be output unchanged by way of 
   the OUTPUT_NOT_CORRELATED clause. 
   
      Note: In a future version of FME, if no CORRELATION_SPEC clauses are 
      defined, every input feature will be considered to match all rows in the 
      table. 
   
   Features that find matching rows in the table are output with the new feature 
   type, as specified in the OUTPUT_FEATURE_TYPE_COLUMN. If more than one 
   feature type is specified in this column in different matching rows, more 
   than one copy of the input feature will be produced. If the 
   OUTPUT_FEATURE_TYPE_COLUMN clause is omitted, then the feature type of all 
   output features will be the same as they were when input.
   
   Before the feature is output, the CORRELATION_COLUMNS clause settings are 
   used to modify the attributes of the feature. For each of these clauses, the 
   value in the <input attrname column name> specifies the name of an attribute 
   that will be duplicated as a new attribute with the name found in the <output 
   attrname column name>. This attribute modification, defined on the 
   CORRELATION_COLUMNS clauses, is done for each row that matches the feature.
   
   If several copies of the input feature are being output because more than one 
   output feature type is specified, the new attributes will only be added to 
   the output feature with the feature type specified in the 
   OUTPUT_FEATURE_TYPE_COLUMN of that particular row.
   
   If the input feature does not have any value associated with the input 
   attribute and the <default attribute value column name> is specified, the 
   value in this column will be supplied to the output attribute on the output 
   feature. 
   
   If the <input attrname column name> column is blank, then the new attribute 
   is simply added with the default value. 
   
   If the <output attrname column name> column is blank, the original attribute 
   will be removed. 

Output Tags

   The CorrelationFactory supports the following output tags.

   CORRELATED  
   
      These are the features that result from applying the manipulations 
      specified in the associated database table.

   NOT_CORRELATED 
   
      These are the original, unchanged input features that had no matching 
      entries in the associated database table.