Most people understand the use of keyfields for the
input side of the map. (If you don’t,
let me know, we can do an entry on that)

But there seems to be some confusion on using
keyfields on the output side of the map.

Some may think it’s used to skip unwanted/empty
iterations of a repeating structure, but that’s not the case.

The option to add a keyfield on the output side of
a map was necessary for the first versions of the translator, thru Gentran
Server for Windows 2.x.

In those early versions, it was not necessary for
a link to contain data, to cause the map to trigger the output record. As long as data was present at that level,
then it would trigger the output record.
Any other rules on the output record would run, and you would have
unwanted records.

The keyfield was included, to specify that you
only wanted those records that had data in the selected field. The field selected for the keyfield, would be
a mandatory field, or a field that you would expect to be in the output data.

It is NOT recommend to use the following setting,
but you can simulate the behavior of the early versions of the translator by
checking this box in the Details of the map:

That option was added in Gentran Server for Windows
3.0, to be backwards compatible, for any users that relied on the translator to
not need data within links, to trigger an output record.It is still present today, for the same
reason, but is strongly discouraged from being used in any of the current
versions.

With that said, here are examples of what the
keyfield on the output side was originally used for, when it was needed.

Here is a simple map, a header record with 2
records inside a repeating group.The 2nd
fields on the output side, have extended rules that just set the field to
“test”.

The input data contains:

HDRHeader

01one a

02two a

01one b

01one c

01one d

01one e

02two e

01one f

01one g

Note that the 02 record is only present for “a”
and “e”. There is no 02 record for
“b”,”c”,”d’,”f” and “g”.

With the way 2.x translators behaved, you would
get the following output.

HDRHeader

01one a
test

02two a
test

01one b
test

02
test

01one c
test

02
test

01one d
test

02
test

01one e
test

02two e
test

01one f
test

02
test

01one g
test

02
test

Notice how you get an 02 record in the output for
every iteration of the Group that was read in.

There were 7 iterations of the group, so 7 02s
were written out. The 8th
iteration was empty, so the translator stopped processing then.

This obviously wasn’t acceptable behavior, so the
keyfield on the output side was added.

Select a field that will have data, in the
properties of the ouput reccord:

When you run the map with the keyfield selected,
you get the same behavior as you expect today:

HDRHeader

01one a
test

02two a
test

01one b
test

01one c
test

01one d test

01one e
test

02two e
test

01one f
test

01one g
test

The only 02 records are those that have data
linked across to the field in the keyfield.

With the enhancements done for Gentran Server for
Windows 3.x and newer (including all
versions of GIS/SI). The
translator was modified to only trigger the output record, when data is present
in at least one field that is linked to the output record.

With the current translators, the only time the
keyfield will come into play, is when there are multiple fields linked:

With the data:

HDRHeader

01one a

02two a
two aa

01one b

02
two bb

01one c

02two c

Note that “a” and “aa” are present, “b” is not
present, but “bb” is, “c” is present but “cc” is not present.

With the current translators, as long at least 1
link has data, it will trigger the output record:

HDRHeader

01one a
test

02two a
two aa

01one b
test

02
two bb

01one c
test

02two c

When
you add a keyfield on the output record:

This will only output the 02, where the first field
is present:

HDRHeader

01one a
test

02two a
two aa

01one b
test

01one c
test

02two c

Note the 02 for “bb” is not in the output, since there
was no “two b”.

The use of the keyfield in this aspect, is getting
away from the original design of why the keyfield was added to the
product. As I mentioned in the
beginning, the 2.x check box and the keyfield on the output are still in the
product for backward compatibility.

Looking at all these examples, it may look like
it’s skipping the unwanted/empty iterations of the 02 records. But this is all due to the fact that the 01
and 02 are in a repeating group.

To expanded on how the translator processes data,
it will continue to evaluate the links for the output records, until it finds
an empty iteration for the current REPEATING STRUCTURE on the output side.

So in this case, the repeating structure is the
Group. As long as those 01 records are
present, it will continue to evaluate the 02 record as well.

As soon as there are no 01 or 02 records for the
output, then it will stop evaluating, and leave the current repeating
structure.

If you have a repeating record, instead of a
repeating group:

With input data:

HDRHeader

01one a
two a

01one b
two b

01one c

01one d
two d

01one e

01one f
two f

01one g
two g

It will evaluate all 8 iterations, for 2.x,
without a keyfield:

HDRHeader

01test
two a

01test
two b

01test

01test
two d

01test

01test
two f

01test
two g

Again, because there just has to be data read in
for each level.

If you add a keyfield or test it both with and
without a keyfield with the current translator, it stops at the empty
iteration:

HDRHeader

01test
two a

01test
two b

The same holds true, for when a repeating record
has multiple links to it.

As soon as the keyfield does not have data in it,
it will cause an empty iteration.

So, the keyfield is not allowing the translator to
skip unwanted/empty iterations. As soon
as it finds an empty iteration, it stops evaluating the rest of the maximum for
the repeating structure.

Hopefully this clears up the design and use of the
keyfield on the output side of the map.

It really is only still in the product, because
they have to keep the backwards compatibility as an option.

The same goes for the “2.x compatible” check box.

The next time you come across the keyfield on the
output side of the map, you’ll have a better understanding as to what it’s
doing. I usually end with saying that it’ll
make your mapping life that much easier, but if you were hoping for it to allow
you to skip unwanted iterations, that’s not the case.