Structure Mapping

There are occasions when it is useful to be able to process more than one repository structure at the same time, or at least to have the ability to make references to a second structure, or fields in the second structure.

For example, consider the situation where you are creating routines which you will use to access data in a relational database table. One of the routines that you create might be responsible for creating a relational database table based on the attributes of a repository structure (fields become columns, etc.). You may find that the repository structure does not quite meet the requirements of what you are trying to achieve. For example, you may want to assign different names to the columns it the database table, omit some fields from the table, or perhaps change some data types. You can’t change the current repository structure to meet your new requirements, because that would impact your other applications, and obviously the current structure needs to match the layout of the actual data file.

To assist in addressing issues like these, CodeGen allows you to create a new repository structure and then “map” the new structure to an existing structure. You can also map fields in the new structure to fields in the original structure.

To map a new structure to an existing structure you add a special code into the new structures long description or user text field, like this:

@MAP=original_structure;

To map fields in your new structure to fields in an existing structure, add @MAP={otherfield}; to the new fields long description or user text string, like this:

@MAP=original_field;

Note that in both cases it is important that the word MAP appears in uppercase, and there should be no spaces between the leading @ character and the trailing ; (semi-colon) character.

Creating Mapped Structures

To assist you in creating mapped structures in the repository, CodeGen includes a utility program called MapPrep. This utility can significantly reduce the amount of effort required to create mapped structures, especially when the structure has a large number of fields.

Mapped Field Conversions

When performing field mapping, you may optionally specify functions to be called when data is mapped into the field in the new target structure, or unmapped back into the field in the original structure. This can be useful if you need to perform transformations on the data as mapping occurs. For example, you may wish to convert the data in a description field between uppercase in the original field, and mixed case in the new field, or convert between a decimal field in the original structure and an implied decimal in the new structure.

To specify a mapping conversion function for a mapped field you add another special code in the fields’ user text string or long description, like this:

@MAPF=mapping_function;

To specify a mapping un-conversion function for a mapped field you add another special code in the fields’ user text string or long description, like this:

@UNMAPF=unmapping_function;

Writing Conversion Functions

Mapping and unmapping functions must be declared as external functions, with a return value data type which matches the target field. They must accept a single parameter which is used to pass in the original value to be mapped or unmapped. For example:

function DivideBy100, d.
          required in originalValue, d
          endparams
proc
          freturn (originalValue / 100.0)
endfunction