Mapping Files

A mapping file can be used to control how data is converted from source to target entities when importing or copying data. The mapping file contains the copy instructions.

It can be used using the /cpy command line switch, and with the ProcScript commands $ude("import"), $ude("copy"), and entitycopy. For more information, see Export and Import Facilities and Data Copy Facility.

Changes to field and entity definitions in the application model can alter the physical structure of the underlying database tables or files. To avoid data loss, you can use mapping files to convert data copied from existing definitions to match the new model definitions. A mapping file allows you to specify exactly how data in each source entity is copied to the target entity.

Use mapping files when you need to:

Add fields to an existing entity or change the lengths of fields
Split an existing entity into several entities
Selectively copy parts of an existing entity to another entity

You can create mapping files using a text editor.

Note: If you do not use a mapping file when copying data, the definitions of target entities are taken from the data source, not the target.

Mapping File Contents

A mapping file is organized into sections, with each section representing one entity mapping. Each section contains:

Map header—indicates the start of a group of mapping instructions:
#map
The map header is optional if there is only one section in the mapping file.
Entity mapping instruction—specifies the source and target entities. The syntax is as follows:
```
TargetEntity.Model {=} SourceEntity.Model
```
The target and source entities can be separated by an equals sign (=), spaces, or tabs.
Note: You can also specify "* = *" to map all source entities to their corresponding target entities.
Optionally, a Copy corresponding instruction—a line containing an asterisk (*).
This indicates that for each pair of fields in the source and target entities that have the same field name, the contents of the source field should be copied to the target field.
All fields in the target entity that are not mapped by a copy corresponding instruction are made empty.
Zero or more field mapping instructions—each field mapping specifies a source and target field. The syntax is as follows:
```
TargetField {=} SourceField {[{Test,}{MapChars}]}
```
Use unqualified field names (that is, without the associated entity name appended) for the sources and target fields. The target and source fields can be separated by an equals sign (=), spaces, or tabs. The optional extraction parameters Test and MapChars are described in the tables.

Test Parameter for Field Mappings
Form of Test	Meaning
(omitted)	Use MapChars to map the characters from SourceField to TargetField.
=x	If the first character in SourceField matches x, use MapChars to map the data to TargetField. If the first character does not match x, no data is copied.
!x	If the first character in SourceField does not match x, use MapChars to map the data to TargetField. If the first character matches x, no data is copied.
?x	If the first character in SourceField matches x, use MapChars to map the data to TargetField. If the first character does not match x, copy the entire field to TargetField.

MapChars Parameter for Field Mapping
Form of MapChars	Meaning
(omitted)	Copy all data from SourceField to TargetField.
n	Skip n characters before copying.
{n}, m	Skip n characters, then copy m characters. If n is omitted, copy the first m characters.
{n,}<x	Skip n characters, then copy up to, but not including, the next character x that occurs in SourceField. If x is not found, TargetField is filled with the remaining characters.
{n,}>x	Beginning after the first character x that occurs in SourceField, skip n characters, then copy the remaining characters in SourceField to TargetField. If x is not found, TargetField is empty.

A section is terminated by a blank line, another map header or the end of the mapping file. This means that, while you can use blank lines between the sections of a mapping file, you may not include blank lines within a section.

On each line of the file, any characters following a semicolon (;) are treated as comments. This means that a line may contain only a comment or it can have a map instruction followed by a comment.

Mapping Errors

When a mapping file is used to import or copy, problems are reported by $ude and entitycopy in the DETAILS of $procreturncontext:

Restrictions

The following restrictions apply to mapping instructions:

The field data type defined in the application model for the source and target fields must be the same. If they are not, the results are unpredictable.
Syntactic and semantic checks are not performed as the data is copied.
Included entities can be mapped only when there is a single occurrence of the included entity.
The Test and MapChars parameters are based on the physical contents of the data in the field. This means that you should use these parameters only with seven-bit character fields (that is, Uniface Font 0)

Caution: Uniface does not check for these restrictions. They are your responsibility.

Field Mapping Instructions
Field mapping instruction	Contents of IN	Contents of OUT
OUT=IN	ABCDEFGHIJ	ABCDEFGHIJ
OUT=IN[3]		DEFGHIJ
OUT=IN[,4]		ABCD
OUT=IN[3,4]		DEFG
OUT=IN[<F]		ABCDE
OUT=IN[3,<F]		DE
OUT=IN[>C]		DEFGHIJ
OUT=IN[3,>F]		J
OUT=IN[=A]	ABCDEFGHIJABCD	ABCDEFGHIJ
OUT=IN[=a]		(null)
OUT=IN[=A,3]		DEFGHIJ
OUT=IN[!A]	ABCDEFGHIJ	(null)
OUT=IN[!a]		ABCDEFGHIJ
OUT=IN[!a,4]		ABCD
OUT=IN[?A]	ABCDEFGHIJ	ABCDEFGHIJ
OUT=IN[?A,<F]		ABCDE
OUT=IN[?A,>J]		(null)
OUT=IN[?a]		ABCDEFGHIJ