Mapping techniques

Using the following mapping techniques will make your mapping project easier and more efficient.

Common mapping techniques

Commands and command groups

Mapping commands are instructions that tell Data Interchange Services client what operation needs to be performed to accomplish a very specific task. Put a coordinated set of mapping commands together and a document can be transformed from one format to another. Mapping commands are represented as nodes on the tree in the Mapping Command window. Most mapping commands can be placed almost anywhere on the tree contained in the Mapping Command window. Some placement limitations exist, depending on the command and its parent node. Mapping commands can exist on their own or be contained within a command group.

A command group generally contains a set of related mapping commands and comments. A mapping command is displayed as a single node on the tree in the Mapping Command window. Grouping a set of related commands and comments together allows the set of related commands and comments to collapse to a single node on the tree. You can copy the command group instead of having to move or copy each mapping command or comment individually. Command groups can contain a description. Use the description to describe the mapping commands and comments contained within the command group.

Important:
The following mapping commands cannot be placed into a command group: Qualify(), Default, ForEach(), HLLevel(), HLDefault, and HLAutoMapped.

The following icons are used to display the various mapping command related nodes on the tree in the Mapping Command window:

Map icons

Icon Description
Represents most mapping commands
Represents a command group
Represents conditional commands such as If()/ElseIf()/Else/EndIf
Represents the Qualify() and Default commands
Represents the ForEach() command
Represents the special hierarchical loop mapping command (HLLevel())
Represents the special default hierarchical loop mapping command (HLDefault)
Positioned to the right of a mapping command icon to indicate there is an error in the mapping command. A description of the error is contained within parenthesis following the mapping command

Comments and comment groups

Comments are nodes in the Mapping Command window that contain a comment describing anything useful about the map. They can describe what the mapping commands that follow the comment accomplish or they can document changes to the map. Comments can also be useful to document change history or revisions to a particular map. For example, comments can specify the date, time, person who made the change, and why the change was made. A comment can be placed almost anywhere in the tree contained in the Mapping Command window. Each comment is displayed as a single node on the tree in the Mapping Command window. Comments can exist on their own or be contained within a comment group.

A comment group is used to group a set of related comments together. This allows the set of related comments to collapse to a single node on the tree. You can move or copy the comment group instead of having to move or copy each comment individually. Comment groups can contain a description. Use the description to describe the comments contained within the comment group. The following figure shows comments documenting changes to the map. The comments are contained within a comment group. This is one method of creating a revision list for your map.

Grouped comments

The following icons are used to display comments and comment groups on the tree in the Mapping Command window:

Comment icons

Icon Description
Represents a comment
Indicates a comment group

Variables

Variables are used in programming languages to store and manipulate data. Maps also support variables. Three types of variables are supported: local variables, global variables, and special variables. Variables are used in mapping commands and functions, commonly within expressions.

Variables must exist before they can be used in mapping commands and functions. Use the Variables window to create the needed Global Variable or Local Variable. To use an existing variable, click on the variable, continue to hold the mouse button down, then drag the variable to a simple element in the Source or Target Document Definition window or to another variable. Once over the desired position, release the mouse button to "drop" the variable. Performing this action will create an assignment statement in the Mapping Command window.

In source-based maps, the assignment statement is placed within the corresponding simple element in the Mapping Command window when the variable is dropped on a simple element in the Source Document Definition window or in the Mapping Command window. If the drop target is a simple element in the Target Document Definition window or is another variable, the assignment statement is created within the selected node in the Mapping Command window. This is true unless the node does not support embedded commands, in which case the assignment statement is placed after the selected node. When the variable is dropped on a simple element in the Source Document Definition window or in the Mapping Command window, the assignment command results in the data contained in the simple element being copied to the variable. When the variable is dropped on a simple element in the target document definition, the assignment statement results in the data contained in the variable being copied to the simple element in the target document. When a variable is dropped on another variable, the assignment statement results in the data contained in the variable being dragged being copied to the variable that it was dropped on.

In target-based maps, the assignment statement is placed within the corresponding simple element in the Mapping Command window when the variable is dropped on a simple element in the Target Document Definition window or in the Mapping Command window. If the drop target is a simple element in the Source Document Definition window or is another variable, the assignment statement is created within the selected node in the Mapping Command window. This is true unless the node does not support embedded commands, in which case the assignment statement is placed after the selected node. When the variable is dropped on a simple element in the Target Document Definition window or in the Mapping Command window, the assignment command results in the data in the variable being copied to the simple element. When the variable is dropped on a simple element in the Source Document Definition window, the assignment statement results in the data contained in the simple element in the source document being copied to the variable. When a variable is dropped on another variable, the assignment statement results in the data in the variable being copied to the variable that it was dropped on.

Variables can also be dragged to the Mapping Command Editor. Drop the variable in the command wherever needed. Names of variable can be typed into the Mapping Command Editor also. Use variables in mapping commands and functions as needed. The data within variables can be freely manipulated using the various commands and functions that are available with the exception of special variables. Data can be assigned to special variables, but data can not be obtained from special variables.

Local variables

Local variables are unique to the map they are defined in. A local variable must be defined to a map before it can be used in that map.

Local variables have a scope of document or loop. During translation, local variables defined with a scope of document will be created at the start of every document and deleted at the end of the document. Variables defined with a scope of loop will be created and initialized whenever a new loop iteration is started, and destroyed at the end of each loop iteration. A loop variable does not disturb the value of another variable with the same name at another level of looping. Local variables are maintained within the map they are defined. A user may add, delete, and alter the properties of any local variable.

Global variables

Global variables are similar to local variables, except they are not unique to any map; they are shared across data transformation maps, validation maps, and functional acknowledgment maps.

Global variables have a scope that is group- or interchange-oriented. Variables that have a scope of interchange are created when an interchange is encountered. They are reset at the start of the next interchange. Variables with a scope of group are created when a group is encountered. They are reset at the start of the next group. Not all syntax types support the concept of groups or interchanges. When the source document type does not support groups, the scope of group is treated the same as interchange. If the document type does not support interchanges, the variable is reset at the start of each input document. For example, if the input file contains multiple document and is split into separate documents by the RODSplitter or XMLSplitter, the global variables are reset for each input ROD or XML document in the file.

The difference between a global variable and a local variable is the scope of the variable. The scope of a variable indicates when a variable is created during translation and how long it will exist. Local variables are created at the document or loop level. They are map-specific and are created and maintained within a map editor. Global variables are independent of the document and can span documents. Global variables can be created and updated within a map; however, general maintenance of global variables is performed from the Global Variables list window.

Special variables

Special variables are a group of predefined variables used by Data Interchange Services client. They function much like local variables or global variables, except that they each have a special purpose.

A user can view the properties of a special variable, but no changes can be made. Special variable names always start with "DI". It is recommended that you do not start local variables or global variable names with "DI".

Special Variables are write-only. That means that you can set the value of a special variable, but you cannot read it or use it in an expression. Special variables are used in data transformation maps and functional acknowledgment maps. They are currently not useful in validation maps.

The following special variable is supported:

Drag and drop

Data Interchange Services client allows you to perform many mapping tasks by dragging and dropping.

You can use drag and drop to perform the following mapping tasks:

Important:
For moving or copying commands, command groups, comments, or comments groups, if the new location is not visible in the mapping window, just hold the drag and move up or down in the mapping window and Data Interchange Service client automatically scrolls up and down. If the new location has not been expanded (indicated by a '+' sign), just hold the drag over the node and Data Interchange Service client will automatically expand that node.

Using the Mapping Command window

The Mapping Command window allows you to apply the advanced mapping capabilities of Data Interchange Services client.

The following steps describe how to use the Mapping Command window.

  1. Open the Mapping Command window. The following steps describe how to do this.
    1. From the main application window, click the Mapping button. This opens the Mapping list window.
    2. From the Mapping list window, select the tab that represents the type of map you want to work with. The choices are: Data Transformation Map, Validation Map, and Functional Acknowledgment Map. The map list window for your selected map type appears.
    3. From the map list window, double-click the map you want to work with. The map loads, then the Map Command window opens. The following figure displays the Mapping Command window.
  2. Right-click an element in the Mapping Command window and follow the cascading menus. You can choose to insert a command, command group, comment, or comment group. You can choose to insert your selection before, after, or within the element you have selected.
  3. If you want to insert a command, select where the command should be inserted, select Command, and then select the command to be inserted. The Mapping Command Editor appears with a prototype of the command.
  4. Edit the prototype to create the command you need. A right-click on the prototype parameters will display a list (if any) of the possible commands and functions available for that parameter. A click or selection on the command or function will replace the prototype parameter with the selection. For functions, the parameter will be replaced with the prototype for that function.
  5. Click Insert if you want to add the command, and create another one similar to it.
  6. Click OK when you have your last command ready.
    Note:
    The command list contains a "Find" command. This can be useful in finding a particular mapping command, source path, target path, or variable.

Simple elements

You can use a drag and drop operation to create a mapping command that will copy data from a simple element in the source document to a simple element in the target document.

In a source-based map, the drag operation creates a MapTo() command. The command is inserted into the Mapping Command window within the element corresponding to the source element in the drag operation. Execution of the command during translation of the source document results in data contained in the element in the source document being copied to the element in the target document. If the simple element in the source document definition is repeating, the mapping command is executed each time the source element is encountered in the source document. When this occurs and the simple element in the target document definition is also repeating, a new occurrence of the element in the target document is created for each occurrence of the simple element in the source document. If the simple element in the target document definition is not repeating, then each occurrence of the simple element in the source document overwrites the data contained in the one simple element in the target document. If the simple element does not exist in the source document, the target element will not be created.

In source-based maps, the Mapping Command window contains a representation of the source document layout, similar to the document definition displayed in the Source Document Definition window. Elements in the Mapping Command window correspond to elements in the Source Document Definition window. As a result, simple elements in the Mapping Command window can be dragged instead of simple elements in the Source Document Definition window. The one exception to this is involving simple elements within nested hierarchical loops. When mapping simple elements within nested hierarchical loops, perform drag operations using the Mapping Command window instead of the Source Document Definition window. This ensures that the paths associated with the nested elements include the nesting levels when placed in mapping commands.

For source-based maps, if there is a qualification on the simple element (Qualify() and Default commands), the MapTo() mapping command is inserted within the qualification that contains the current selected node. If the current selected node is not within one of the qualifications, the command is inserted into the qualification that is expanded if only one is expanded. If it cannot be determined where the command should be inserted, an error message is displayed asking you to select a qualification and then repeat the drag operation.

In target-based maps, a drag of a simple element from the Source Document Definition window to the Target Document Definition window creates a MapFrom() command. The command is inserted into the Mapping Command window within the element corresponding to the target element in the drag operation. Execution of the MapFrom() command during translation of the source document results in data contained in the corresponding source element being copied to the element in the target document. If the simple element in the Target Document Definition window occurs more than once (repeats), a ForEach() command is also inserted in the Mapping Command window. The ForEach() command will be inserted into the Mapping Command window within the element corresponding to the target element in the drag operation. The MapFrom() command is placed within the ForEach() command. The ForEach() command indicates that for every occurrence of the simple element in the source document, an occurrence of the simple element in the target document is created. A single simple element can have multiple ForEach() commands associated with it.

In target-based maps, the Mapping Command window contains a representation of the target document layout, similar to the document definition displayed in the Target Document Definition window. Elements in the Mapping Command window correspond to elements in the Target Document Definition window. As a result, drag operations can end on simple elements in the Mapping Command window instead of ending on simple elements in the Target Document Definition window. The one exception to this is involving simple elements within nested hierarchical loops. When mapping simple elements within nested hierarchical loops, perform drag operations using the Mapping Command window instead of the Target Document Definition window. This ensures that the paths associated with the nested elements include the nesting levels when placed in mapping commands.

Compound elements

Generally, you can drag and drop operations to map compound elements.

In a source-based map, the drag operation will create a MapTo() command. The command is inserted into the Mapping Command window within the element corresponding to the source element in the drag operation. Execution of the command during translation of the source document results in the creation of an occurrence of the compound element in the target document each time the compound element in the source document occurs.

In source-based maps, the Mapping Command window contains a representation of the source document layout, similar to the document definition displayed in the Source Document Definition window. Elements in the Mapping Command window correspond to elements in the Source Document Definition window. As a result, compound elements in the Mapping Command window can be dragged instead of compound elements in the Source Document Definition window. The one exception to this is involving compound elements within nested hierarchical loops. When mapping compound elements within nested hierarchical loops, perform drag operations from the Mapping Command window instead of the Source Document Definition window. This ensures that the paths associated with the nested elements include the nesting levels when placed in mapping commands.

For source-based maps, if there is a qualification on the compound element (Qualify() and Default commands), the MapTo() mapping command is inserted within the qualification that contains the current selected node. If the current selected node is not within one of the qualifications, the command is inserted into the qualification that is expanded if only one is expanded. If it cannot be determined where the command should to be inserted, an error message is displayed asking you to select a qualification and then repeat the drag operation.

In target-based maps, a drag of a compound element from the Source Document Definition window to the Target Document Definition window will create a ForEach() command. The command is inserted into the Mapping Command window within the element corresponding to the target element in the drag operation. Execution of the ForEach() command during translation of the source document results in an occurrence of the compound element in the target document being created for every occurrence of the compound element in the source document, unless the compound element in the target document is non-repeating. In this case, only one occurrence of the compound element in the target document is created. Subsequent occurrences of the compound element in the source document may overwrite the one occurrence of the compound element in the target document definition. If the compound element in the target document does not repeat, you may need to use qualification (Qualify() and Default commands) or conditional mapping commands (If()/ElseIf()/Else/EndIf) to ensure a second occurrence of the compound element in the source document definition does not overwrite the first occurrence of the compound element in the target document. A single compound element can have multiple ForEach() commands associated with it.

In target-based maps, the Mapping Command window contains a representation of the target document layout, similar to the document definition displayed in the Target Document Definition window. Elements in the Mapping Command window correspond to elements in the Target Document Definition window. As a result, drag operations can end on compound elements in the Mapping Command window instead of ending on compound elements in the Target Document Definition window. The one exception to this is involving compound elements within nested hierarchical loops. When mapping compound elements within nested hierarchical loops, perform drag operations in the Mapping Command window instead of the Target Document Definition window. This ensures that the paths associated with the nested elements include the nesting levels when placed in mapping commands.

Copyright IBM Corp. 2003, 2005