source: branches/species/HELP_SOURCE/source/xferset.hlp

#       main topics:
UP      arb.hlp
UP      glossary.hlp

#       sub topics:
#SUB     subtopic.hlp

# format described in ../help.readme


TITLE           Field transfer sets

OCCURRENCE      ARB_NT/File/Import/Import from external format/FTS
                ARB_NT/File/Export/Export to external format/FTS
                ARB_MERGE/Transfer species/FTS

DESCRIPTION     In the "Select field transfer set" window you may

                * select or edit an existing field transfer set (FTS)
                * create new FTS
                * copy or rename a FTS
                * delete FTS

                To modify a FTS and define the single transfer rules, select the
                FTS and press the EDIT button.
                Another window named "Define rules for field transfer" will open.

SECTION         Define rules for field transfer

                The left of the three lists shown in this windows displays
                the rules defined in the currently selected FTS.

                Select a rule from the list to
                 * modify it (by changing the displayed properties) or to
                 * delete it (using the DEL button below the list).

                Use the ADD button to insert a new, empty rule. Then select
                input and target fields to specify its function.

                Use the COPY and PASTE buttons to copy single or multiple
                rules:
                 * each click to COPY copies the currently selected rule
                   onto an internal stack.
                 * each click to PASTE takes the last rule (copied onto the stack)
                   and inserts it before the currently selected rule.
                 * COPY&PASTE may be used to reuse rules (even in a different FTS).

SECTION         Transfer rule elements

                Each transfer rule consists of the following elements:

                  * one or multiple input fields (shown in the middle list),
                  * a separator used when concatenating multiple fields,
                  * an optional ACI expression (see LINK{aci.hlp}) to postprocess the (concatenated) input data,
                  * the name of the target field where data shall be written to,
                  * type information for that target field and
                  * whether lossy conversion should be accepted or not.

SECTION         Field selection

                The selection list on the right side of the window
                shows all detected fieldnames.

                    Depending on where FTS are used from, it'll be filled with all fields
                     * probably imported or exported by the currently selected import or export filter,
                     * existing in the target and/or source database or
                     * defined by the current FTS.

                The selector above that list allows to select which of these fields
                get displayed. The selectors "input", "output" and "ruleset" select the sets
                listed at the bullets above.
                The selectors "unread" and "unwritten" may be used to detect
                untransferred data and contain the same as "input"/"output" when no ruleset
                is selected, otherwise they lack all fields which are already used in a rule.

                Click on a fieldname in that list to select it; it will show
                up in the textbox below. Alternatively you may type a name there.
                Once a name is specified there

                 * click FROM to add the current field to the list of input fields,
                 * click TO to use it as target field,
                 * hit ENTER to show only fields containing the text or
                 * click CLEAR to clear the textbox again.

                You may specify a hierarchical fieldname, e.g. "misc/value" to create
                a field "value" inside a container "misc".

                Below the list of input fields there are some buttons to edit that list:
                 * the DROP button will remove the selected input field and
                 * the UP and DOWN buttons will move the position of the selected input field.

SECTION         Transfer undefined fields

                If the 'Transfer undefined fields?' toggle below the left list
                is checked, all fields

                 * that were not transferred by the ruleset (i.e. neighter read nor written) and
                 * that do not yet exist in target item (e.g. when used in mergetool)

                will be transferred automatically.

                This includes completely unused sub-containers:
                if no field from inside such a container is used by the ruleset,
                the whole container will be transferred to the target.

NOTES           Transfer rules lacking input data do not generate output data.
                That applies to single AND multiple input fields.
                If some input fields are missing and other exist, the concatenation is
                performed using the existing fields only.

                In most cases the order of the rules in a FTS does not matter.
                If you like to change the order you may either use COPY, DEL + PASTE
                buttons to move rules or use an external editor on the .fts file.

EXAMPLES        See LINK{arb_import.hlp}, LINK{arb_export.hlp} or LINK{mg_species.hlp}.

WARNINGS        Changes to FTS are instantly applied to the .fts file.
                Undo functionality is not available here.

                Consider to backup your files frequently (always a good idea) or
                create a backup-copy of your .fts file before you edit it.

BUGS            No bugs known