This topic contains the following sections:
Use the Mapping node to construct one or more new messages and populate them with new information, with modified information from the input message, or with information taken from a database. You can modify elements of the message body data, its associated environment, and its exception list.
The headers in the input message are always copied to the output message without modification. You cannot modify message headers in a Mapping node; you must use a Compute node.
These components of the output message can be defined using mappings that are based on elements of both the input message and data from an external database. You create the mappings associated with this node in the mapping file associated with this node by mapping inputs (message or database) to outputs. You can optionally modify the assignments made by these mappings using supplied or user-defined functions and procedures: for example you can convert a string value to uppercase when you assign it to the message output field.
Use the Mapping node to:
The Mapping node is represented in the workbench by the following icon:
When you have put an instance of the Mapping node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.
All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk on the properties dialog.
Configure the Mapping node as follows:
On z/OS systems, the broker uses the broker started task ID.
If you click Browse next to this entry field, a dialog is displayed that lists all available mapping routines accessible by this node. Select the routine that you want and click OK. The routine name is set in Mapping Module.
To work with the mapping routine associated with this node, right-click the node and select Open Mappings. If the mapping routine does not exist, it is created for you with the default name in the default file. If the file already exists, you can also open file <flow_name>_<node_name>.mfmap in the Navigator view.
A mapping routine is specific to the type of node with which it is associated; you cannot use a mapping routine that you have developed for a Mapping node with any other node that uses mappings (for example, a DataInsert node). If you create a mapping routine, you cannot call it from any other mapping routine, although you can call it from an ESQL routine.
You cannot modify message headers in the Mapping node; they are copied unchanged from input message to output message. You must use a Compute node if you want to change the headers in a message.
For more information about working with mapping files, and defining their content, see Developing mappings.
You must set this property to correctly reflect the output message format that you require. If you select an option (or accept the default value) that does not include a particular component of the message, that component is not included in any output message that is constructed.
(In releases prior to Version 2.1, the associated environment (LocalEnvironment) was known as DestinationList. DestinationList is valid and can be used for compatibility.)
(The Environment component of the message tree is not affected by the mode setting. Its contents, if any, are passed on from this node.)
The options are explained in the table below.
Mode | Description |
---|---|
Message (the default) | The message is generated or passed through by the Mapping node as modified within the node. |
LocalEnvironment | The LocalEnvironment tree structure is generated or passed through by the Mapping node as modified within the node. |
LocalEnvironment And Message | The LocalEnvironment tree structure and message are generated or passed through by the Mapping node as modified by the node. |
Exception | The Exception List is generated or passed through by the Mapping node as modified by the node. |
Exception And Message | The Exception List and message are generated or passed through by the Mapping node as modified by the node. |
Exception and LocalEnvironment | The Exception List and LocalEnvironment tree structure are generated or passed through by the Mapping node as modified by the node. |
All | The message, Exception List, and LocalEnvironment are generated or passed through by the Mapping node as modified by the node. |
When you select the box, the node handles all positive return codes from the database as errors and generates exceptions in the same way as it does for the negative, or more serious, errors.
If you do not select the box, the node treats warnings as normal return codes, and does not raise any exceptions. The most significant warning raised is not found, which can be handled as a normal return code safely in most circumstances.
If you clear the box, you must handle the error in the message flow to ensure the integrity of the broker and the database: the error is ignored if you do not handle it through your own processing, because you have chosen not to invoke the default error handling by the broker. For example, you could connect the failure terminal to an error processing subroutine.
The first two options are particularly useful when validation is first invoked because you see all validation failures, not just the first error that is encountered. When you have analyzed the failures, you might typically select Exception for future use.
The failure destinations behave like those for Trace node output. So, for example, if you select User Trace, trace entries are written regardless of the setting of the user trace flag for the message flow.
Click Cancel to close the dialog and discard all the changes that you have made to the properties.
The Mapping node terminals are described in the following table.
Terminal | Description |
---|---|
In | The input terminal that accepts a message for processing by the node. |
Failure | The output terminal to which the input message is propagated if a failure is detected during the computation. If you have selected Treat warnings as errors, the node propagates the message to this terminal if database warning messages are returned, even though the processing might have completed successfully. |
Out | The output terminal that outputs the message following the execution of the database statement. |
The following tables describe the node properties; the column headed M indicates whether the property is mandatory (marked with an asterisk on the properties dialog if you must enter a value when no default is defined), the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).
The Mapping node Basic properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Data Source | No | Yes | The ODBC data source name of the database in which reside the tables to which you refer in the mappings associated with this node (identified by the Mapping Module property). | |
Transaction | Yes | No | Automatic | The transaction mode for the node. Valid values are Automatic or Commit. |
Mapping Module | Yes | No | Mapping | The name of the mapping routine that contains the statements to execute against the database or the message tree. The routine is unique to this type of node. |
Mapping Mode | Yes | No | Message | Select one of the following:
|
Treat warnings as errors | Yes | No | Cleared | Treat database SQL warnings as errors. If you select the check box, this action is performed. |
Throw exception on database error | Yes | No | Selected | Database errors cause the broker to throw an exception. If you select the check box, this action is performed. |
The Mapping node Validation properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Validate | Yes | No | None | Whether validation takes place. Valid values are None and Content and Value. |
Failure Action | Yes | No | Exception | What happens if a validation failure occurs. You can set this property only if Validate is set to Content and Value. Valid values are User Trace, Local Error Log, and Exception. |
Include All Value Constraints | Yes | No | Selected | This property cannot be edited. The default action, indicated by the check box being selected, is that all value constraints are included in the validation. |
Fix | Yes | No | None | This property cannot be edited. Minimal fixing is provided. |
The Mapping node Description properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Short Description | No | No | A brief description of the node. | |
Long Description | No | No | Text that describes the purpose of the node in the message flow. |
Related concepts
Message flows
Message flows, mappings, and ESQL
Message Flow Mapping editor
Related tasks
Setting up DB2
Deciding which nodes to use
Configuring coordinated message flows
Handling errors in message flows
Developing mappings
Editing configurable properties
Related reference
mqsichangebroker command
mqsicreatebroker command
mqsisetdbparms command
Compute node
Datalnsert node
Notices |
Trademarks |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
ac04720_ |