Fieldlist Merging and Mapping
Fieldlist merging with LCFieldlistMerge and LCFieldlistMergeVirtual support field mapping. To perform mapping, two fieldlists are provided, one as the name source and the other as the field/data source. Depending on merge options, a mapping is produced between the names of the name source and the fields of the data source, and a third fieldlist is produced which references parts of the original fieldlists. When using virtual fields and LCFieldlistMergeVirtual, fields in the data fieldlist which match the supplied virtual code are excluded from mapping and are added to a separate new virtual fieldlist.
Mapping and Merging
When a fieldlist is to be used for more than one specific action, there is often a need to have it treated differently by each of those actions. For example, fields in a fieldlist map need to be reordered, renamed, or removed, but only in the context of one particular operation. For such situations, the following four methods are provided to perform this mapping:
- Map
- MapName
- Merge
- MergeVirtual
MergeVirtual is simply a variation of Merge which handles virtual codes as well. These methods produce a new fieldlist from an existing fieldlist, but with the same fields referenced from both fieldlists, allowing two different 'maps' into a set of fields. If these two fieldlists are sent to different Connector methods, then the Connectors will see different sets of fields in a different order, but referring to the same data and common fields.
The three methods Map, MapName, and Merge have various levels of difficulty and control available to the caller; which one is needed depends on the specific situation. In general, the simplest method which supports your requirements should be used. These methods are listed, starting with the simplest.
Map is applicable when the names in the fieldlist are correct, but fields either need to be reordered or removed. It accepts a fieldlist and a text list of names, and the new fieldlist contains the fields from the original fieldlist reordered in the order they are listed in the text list. In addition, any fields not included in the text list are excluded from the new fieldlist.
MapName adds renaming of fields to Map, but is otherwise identical. By adding a second text list of names, it will rename each field in the first text list with the corresponding entry in the second text list.
Merge accepts two fieldlists, one which provides the list of fields, and one which provides the list of names. In addition, it accepts a set of flags which further control the new fieldlist produced. These flags control the type of mapping, whether to allow fields to be excluded from either fieldlist, and how to interact with specific field flags. Merge should only be used when the functionality of Map and MapName is insufficient for your needs, as Merge is much more complex to use.