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:
With that said, here are examples of what the keyfield on the output side was originally used for, when it was needed.
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:
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:
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
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:
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.
As always, any and all comments are welcome.
Feel free to request any topics or ideas as well.
Thanks for reading!
Pat Frey – IBM Support
