Use the Mapping node to construct one or more new messages and populate them with various types of information.
This topic contains the following sections:
When you first open or create a message map for the node, if you select This map is called from a message flow node and maps properties and message body, the headers in the input message are always copied to the output message without modification. To modify the message headers in a Mapping node, select This map is called from a message flow node and maps properties, headers, and message body. When you select this property, the map that is created allows additional elements, including WebSphere MQ, HTTP, and JMS headers, to be mapped.
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 that are associated with this node, in the mapping file that is associated with this node, by mapping inputs (message or database) to outputs. You can 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 contained in the Transformation drawer of the palette, and is represented in the workbench by the following icon:
You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.
When you have put an instance of the Mapping node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view. To display the properties of the node in the Properties dialog, right-click the node and click Properties. (If you double-click the Mapping node, you open the New Message Map dialog box.) All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.
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 mappings. |
The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk 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 Description properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | The node type | The name of the node. |
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. |
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 that
contains the tables to which you refer in the mappings that are associated
with this node (identified by the Mapping
Module property). This name identifies the appropriate database
on the system on which this message flow is to execute. The broker
connects to this database with user ID and password information that
you have specified on the mqsicreatebroker, mqsichangebroker, or mqsisetdbparms command.
|
|
Transaction | Yes | No | Automatic | The transaction mode for the node. The values
are:
|
Mapping Routine | Yes | No | Mapping | The name of the mapping routine that contains
the statements to execute against the database or the message tree.
By default, the name that is assigned to the mapping routine is identical
to the name of the mapping file in which the routine is defined. The
default name for the file is the name of the message flow concatenated
with the name of the node when you include it in the message flow
(for example, MFlow1_Mapping.msgmap for the first Mapping node in message flow
MFlow1). You cannot specify a value that includes spaces. If you click Browse next to this entry field, a dialog box is displayed that lists all available mapping routines that this node can access. Select the routine that you want and click OK; the routine name is set in Mapping Module. To work with the mapping routine that is associated with this node, double-click the node, or right-click the node and click 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 exists already, you can also open file <flow_name>_<node_name>.msgmap in the Broker Development 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. For more information about working with mapping files, and defining their content, see Developing message mappings. |
Mapping Mode | Yes | No | Message | The mode that is used to process information
that is passed through the Mapping node.
Valid values are:
You must set this property to reflect accurately the output message format that you need. 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. You can choose any combination of Message, LocalEnvironment, and Exception components to be generated and modified by the Mapping node. To construct a map that propagates multiple target messages, set this property to LocalEnvironment And Message to ensure that the node executes correctly. LocalEnvironment was known as DestinationList in some previous versions; it is retained 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. |
Treat Warnings as Errors | Yes | No | Cleared | For database warning messages to be treated
as errors, and the node to propagate the output message to the Failure
terminal, select Treat Warnings as
Errors. The check box is cleared initially. When you select the check 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 check 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 safely as a normal return code in most circumstances. |
Throw Exception on Database Error | Yes | No | Selected | For the broker to generate an exception when a database error is detected, select Throw Exception on Database Error. The check box is selected initially. If you clear the check 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 parser options for the Mapping node are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Parse Timing | No | No | On Demand | This property controls when an input message
is parsed. Valid values are On
Demand, Immediate,
and Complete. For a full description of this property, see Parsing on demand. Parse Timing is, by default, set to On Demand, which causes validation to be delayed until it is parsed by partial parsing. If you change this value to Immediate, partial parsing is overridden and everything in the message is parsed and validated, except those complex types with a composition of Choice or Message that cannot be resolved at the time. If you change this value to Complete, partial parsing is overridden and everything in the message is parsed and validated; complex types with a composition of Choice or Message that cannot be resolved at the time cause a validation failure. |
Use XMLNSC Compact Parser for XMLNS Domain | No | No | Cleared | If you select this check box, the outgoing MQRFH2 specifies the XMLNS instead of XMLNSC parser, allowing an external application to remain unchanged. If outgoing messages do not contain MQRFH2 headers, this property has no effect. |
Retain Mixed Content | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in an input message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created. |
Retain Comments | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in an input message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created. |
Retain Processing Instructions | No | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in an input message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created. |
The Validation properties of Mapping node are described in the following table.
If a message is propagated to the Failure terminal of the node, it is not validated. These properties do not cause the input message to be validated. It is expected that, if such validation is required, the validation has already been performed by the input node or a preceding validation node. For more details about validating messages and validation properties, see Validating messages and Validation properties.
Property | M | C | Default | Description |
---|---|---|---|---|
Validate | No | Yes | None | This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit. |
Failure Action | No | No | Exception | This property controls what happens if a validation failure occurs. You can set this property only if Validate is set to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List. |
Include All Value Constraints | No | No | Selected | You cannot edit this property. If the check box is selected (the default), all value constraints are included in the validation. |
Fix | No | No | None | You cannot edit this property. Minimal fixing is provided. Valid values are None and Full. |