Choosing a mapping action

You can add different parts of the message tree to the map input, to the map output, or to both. You can also add the local environment tree. Depending on how you add a message assembly component, this component can be deleted, initialized, or transformed.

Procedure

Identify the action that you want to achieve in your message map to find out how to add a message assembly component into the message map:

To copy a message assembly component unchanged, do not include the component in the message map.
The mapping engine copies the local environment tree and any other headers and folders from input to output, unchanged, when they are not included in the message map.
The mapping engine handles the following components as independent units of transformation:
- The properties tree in the message tree
- The message body in the message tree
- Each header structure in the message tree. For example, the MQMD is treated as one unit, the MQRFH2 header is considered an independent unit, and so on.
- The local environment tree
If any of these units is not included in the message map, the mapping engine copies their contents unchanged.
Note: If the only transform that you define between an input map component and an output map component is the Move transform so that the component is copied over without any modification, you are recommended to remove the component from the message map. The map transformation will be more efficient since the mapping engine will only focus on the structures that do require change.
To read elements of a message assembly component, add the component to the input message assembly only. The Mapping node passes it through unchanged
To modify all the elements of a message assembly component, add the component such as the local environment tree to the input message assembly and to the output message assembly. Then, define transforms between each of its elements.
To modify some elements of a message assembly component, add the component such as the local environment tree to the input message assembly and to the output message assembly. Define a Move transform for the entire component, that is, at folder level, and then specific transforms for each of the elements that you want to transform within an Override function. For more information, see Transforming some elements of a message assembly component by using the Override function.
To initialize a message assembly component, that is, to create a new message assembly component in your output message, add the message assembly component only to the output message assembly. For more information, see Initializing a message assembly component in the output message.
To add a message assembly component, add the message assembly component to the output message assembly and populate at least one field. The Mapping node creates a new output structure containing the results of your transformations.
To delete a message assembly component from the input message, add the message assembly component to the output message assembly and do not set any field. For more information, see Deleting a message assembly component from the output message.

Results

The following table summarizes the mapping engine behavior when you add the local environment tree to your message map. The same behavior applies when you add any of the header folders, such as the MQ headers > MQMD folder, to your message map.

Table 1. Mapping engine behavior when adding the local environment to a message map for transformation
Input element	Output element	Transform defined between the input element and the output element	Mapper behavior
Local environment tree	Local environment tree	A transform operation such as Move is defined between the input local environment tree and the output local environment tree. Additional transforms are defined between some elements of the local environment tree within an Override function to change the value of those elements.	The input local environment tree is copied into the output local environment tree. The elements whose transforms are defined within the Override function have output values different from the input values based on the transformation. The elements outside the Override function maintain the same values in the output local environment tree.
Elements from other message assembly components, database elements whose values are obtained by doing a database read, or a combination of both	Local environment tree	A Move transform is defined between each parent input message assembly structure and its corresponding output message assembly structure. Additional transforms are defined between input elements and the output local environment tree. Note: If you do not define the Move transform between an input and an output message assembly structure from which you use values to set the local environment output elements, then you will lose the message assembly structure in the output message, although your map will perform the transformation correctly.	Each input message assembly structure is copied into its corresponding output message assembly structure. The output local environment variables are defined as per the additional transforms using values from the input elements.
Local environment tree	Local environment tree	None	Delete the original local environment tree. An empty local environment tree is created for the output message.
Local environment tree	None	None	Delete the original local environment tree. An empty local environment tree is created for the output message.
None	Local environment tree	None	Delete the original local environment tree. An empty local environment tree is created for the output message. You might populate some of the fields by using transforms between other input map components such as the message body and the new local environment structure.
Local environment tree	Local environment tree	A transform operation such as Move can be defined between one element from the input local environment tree and one element from the output local environment tree. The rest of the local environment elements do not have transforms defined that specify how to move the input value to the output value.	The output local environment tree is initialized and only the element that has the transform defined has a non default value set.
Local environment tree	Local environment tree	A transform operation such as Move is defined between the input local environment tree and the output local environment tree.	The input local environment tree is copied into the output local environment tree.

What to do next

Configure the message map to include the local environment tree or a message header. For more information, see Customizing a message map to include a message assembly component.