WebSphere Message Brokers
File: ac04600_
Writer: Terry Cowling

Reference topic

This build: July 31, 2007 21:17:26

MQeInput node

Attention: The use of message flows that contain MQeInput and MQeOutput nodes in Version 6.1 is deprecated. The behavior that is described here is intended only for when you are deploying from Version 6.1 to a previous version, and to provide a route for migration. Redesign your flows to remove the MQe nodes and replace them with MQ nodes that are configured to your own specifications and coordinated with your MQe Gateway configuration. For more details, see Migrating a message flow that contains WebSphere MQ Everyplace nodes.

This topic contains the following sections:

Purpose

Use the MQeInput node to receive messages from clients that connect to the broker using the WebSphere MQ Mobile Transport protocol.

The MQeInput node receives messages that are put to a message flow from a specified bridge queue on the broker's WebSphere MQ Everyplace queue manager. The node also establishes the processing environment for the messages. You must create and configure the WebSphere MQ Everyplace queue manager before you deploy a message flow that contains this node.

Message flows that handle messages that are received across WebSphere MQ Everyplace connections must always start with an MQeInput node. You can set the MQeInput node's properties to control the way in which messages are received; for example, you can indicate that a message is to be processed under transaction control.

When you deploy message flows that contain WebSphere MQ Everyplace nodes to a broker, you must deploy them to a single execution group, regardless of the number of message flows. The WebSphere MQ Everyplace nodes in the message flows must all specify the same WebSphere MQ Everyplace queue manager name. If you do not meet this restriction, an error is raised when you deploy.

The MQeInput node handles messages in the following message domains:

  • MRM
  • XML
  • XMLNS
  • XMLNSC
  • JMSMap
  • JMSStream
  • MIME
  • BLOB
  • IDOC

If you include an output node in a message flow that starts with an MQeInput node, it can be any of the supported output nodes, including user-defined output nodes; you do not need to include an MQeOutput node. You can create a message flow that receives messages from WebSphere MQ Everyplace clients and generates messages for clients that use any of the supported transports to connect to the broker, because you can configure the message flow to request the broker to provide any conversion that is necessary.

WebSphere MQ Everyplace Version 1.2.6 is used by WebSphere Message Broker. This version is compatible with later versions of WebSphere MQ Everyplace. Clients that use later versions of WebSphere MQ Everyplace (for example, Version 2.0), work correctly when connected to this node, although additional functionality that is not supported in Version 1.2.6 (for example, JMS support) does not work.

Queue managers are not interchangeable between different versions of WebSphere MQ Everyplace. Nodes must use a queue manager that was created using Version 1.2.6. Similarly, the client must use its own level of the code when creating a queue manager.

z/OS platform You cannot use MQeInput nodes in message flows that you deploy to z/OS systems.

If you create a message flow to use as a subflow, you cannot use a standard input node; you must use an instance of the Input node as the first node to create an In terminal for the subflow.

If your message flow does not receive messages across WebSphere MQ connections, you can choose another supported input node.

The MQeInput node is represented in the workbench by the following icon:

MQeInput node icon

Using the MQeInput node in a message flow

For an example of how this node can be used, consider a farmer who checks his fields to see how well they are irrigated. He is carrying a PDA device with WebSphere MQ Everyplace installed. He sees an area of field that requires water, and uses his PDA and a Global Satellite Navigation link to send a message to an MQeInput node. The data is manipulated using a Compute node, and a message is published by a Publication node so that a remote SCADA device can pick up the message and trigger the irrigation sprinklers. The farmer can see the water delivered to the field, minutes after sending his message.

WebSphere MQ Everyplace documentation

Find further information about WebSphere MQ Everyplace, and the properties of the node, in the WebSphere MQ Everyplace documentation on the WebSphere MQ Web page.

Configuring the MQeInput node

When you have put an instance of the MQeInput node into a message flow, you can configure it. To display its properties, either double-click the node, or right-click the node and click Properties. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

Configure the MQeInput node as follows:

  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this tab.
  2. On the Default tab, set values for the properties that describe the message domain, message set, message type, and message format that the node uses to determine how to parse the incoming message, and the default topic that is associated with the message.
    • If the incoming message has an MQRFH2 header, you do not need to set values for the Default properties because the values can be derived from the <mcd> folder in the MQRFH2 header; for example:
      <mcd><Msd>MRM</Msd><Set>DHM4UO906S001</Set><Type>receiptmsg1</Type>
      <Fmt>XML</Fmt></mcd>

      If you set values, and those values differ from those in the MQRFH2 header, the MQRFH2 header values take precedence.

    • In Message Domain, select the name of the parser that you are using from the drop-down list. You can choose from the following names:
      • MRM
      • XML
      • XMLNS
      • XMLNSC
      • JMSMap
      • JMSStream
      • MIME
      • BLOB
      • IDOC
    • If you are using the MRM or IDOC parser, select the correct message set from the drop-down list in Message Set. This list is populated with available message sets when you select MRM or IDOC as the domain.

      Leave Message Set blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.

    • If you are using the MRM parser, select the correct message from the drop-down list in Message Type. This list is populated with messages that are defined in the message set that you have selected.

      Leave Message Type blank for XML, XMLNS, XMLNSC, JMS, MIME, BLOB, and IDOC parsers.

    • If you are using the MRM or IDOC parser, select the format of the message from the drop-down list in Message Format. This list includes all the physical formats that you have defined for this message set.

      Leave Message Format blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.

    • Enter the message topic in Topic. You can enter any characters as the topic name. When messages pass through the MQeInput node, they assume whatever topic name you have entered. (If you are using publish/subscribe, you can subscribe to a topic and see any messages that passed through the MQeInput node under that topic name.)
  3. On the General tab, set the following properties:
    1. Enter the Queue Name of the WebSphere MQ Everyplace bridge queue from which this input node retrieves messages. If the queue does not exist, it is created for you when the message flow is deployed to the broker.
    2. Set the level of Trace that you want for this node. If trace is active, the trace information is recorded into the file identified by Trace Filename (described below). Choose a level of trace:
      • None (the default). No trace output is produced, unless a fatal error occurs.
      • Standard. Minimal trace output is generated to reflect the overall operations of the node.
      • Debug. Trace information is recorded at a level that helps you to debug WebSphere MQ Everyplace programs.
      • Full. All available debug information is recorded to provide a full record of the node activities.

      If you set the trace level to Debug or Full, you will impact the performance of WebSphere MQ Everyplace, and significant trace files can be generated. Use these options for short periods only.

    3. In Trace Filename, specify the name of the file to which the trace information is written. The directory structure in which the file is specified must already exist; it cannot be created during operation.
    4. Select the Transaction Mode to define the transactional characteristics of how this message is handled:
      • If you select Automatic, the incoming message is received under syncpoint if it is marked persistent; otherwise it is not. The transactionality of any derived messages that are sent subsequently by an output node is determined by the incoming persistence property, unless the output node has overridden transactionality explicitly.
      • If you select Yes, the incoming message is received under syncpoint. Any derived messages that are sent subsequently by an output node in the same instance of the message flow are sent transactionally, unless the output node has overridden transactionality explicitly.
      • If you select No, the incoming message is not received under syncpoint. Any derived messages that are sent subsequently by an output node in the message flow are sent non-transactionally, unless the output node has specified that the message must be put under syncpoint.
    5. The Use Config File check box is not selected by default; values for all properties for the MQeInput node are taken from the Properties view.

      If you select the check box, the definition of all properties is extracted from the file that is identified by Config Filename (described below) with the exception of the following properties:

      • The Queue Name and Config Filename General properties
      • All Default properties
      Use a configuration file only to specify additional properties for the node. If the properties in the Properties view are sufficient for your needs, do not select the Use Config File check box.
    6. If you have selected the Use Config File check box, enter the full path and name of the configuration file for WebSphere MQ Everyplace in Config Filename. This file must be installed on the system that supports every broker to which this message flow is deployed. If the file does not exist, an error is detected when you deploy the message flow. The default file name is MQeConfig.ini.
    7. In Queue Manager Name, specify the name of the WebSphere MQ Everyplace queue manager. This queue manager is not related to the queue manager of the broker to which you deploy the message flow that contains this node.

      Only one WebSphere MQ Everyplace queue manager can be supported. Only one execution group can contain MQeInput or MQeOutput nodes. This property must therefore be set to the same value in every MQeInput node that is included in every message flow that you deploy to the same broker.

  4. On the Channel tab, set the maximum number of channels that are supported by WebSphere MQ Everyplace in Max Channels. The default value is zero, which means that there is no limit.
  5. On the Registry tab, set the following properties:
    1. Select the type of registry from the Registry Type drop down list:
      • File Registry. Registry and security information is provided in the Directory specified below.
      • Private Registry. You create the queue manager manually within WebSphere MQ Everyplace, specifying the security parameters that you need.
    2. In Directory, specify the directory in which the registry file is located. This property is valid only if you have selected a Registry Type of File Registry.
    3. If you have selected a Registry Type of Private Registry, complete the following properties (for further details of these properties, refer to the WebSphere MQ Everyplace documentation):
      • Specify a PIN for the associated queue manager.
      • Specify a Certificate Request PIN for authentication requests.
      • Provide a Keyring Password to be used as a seed for the generation of crypto keys.
      • In Certificate Host, specify the name of the certificate server that WebSphere MQ Everyplace uses for authentication.
      • In Certificate Port, specify the number of the port for the certificate server that WebSphere MQ Everyplace uses for authentication.
  6. On the Listener tab, set the following properties that define the connection type for WebSphere MQ Everyplace:
    1. In Listener Type, select the adapter type to use from the drop-down list. The default value is Http; you can also select Length or History. For further details, refer to the WebSphere MQ Everyplace documentation.
    2. In Hostname, specify the hostname of the server. Set this property to the special value localhost or to the TCP/IP address 127.0.0.1 (the default value), both of which resolve correctly to the hostname of the server to which the message flow is deployed. You can also use any valid hostname or TCP/IP address in your network, but you must use a different message flow for each broker to which you deploy it, or configure this property at deploy time.
    3. In Port, specify the port number on which WebSphere MQ Everyplace is listening. If more than one MQeInput node is included in a message flow that is deployed to a single broker, each MQeInput node must specify a different number for this property. You must also ensure that the number that you specify does not conflict with other listeners on the broker system; for example, with WebSphere MQ. The default value is 8081.
    4. In Time Interval, specify the timeout value, in seconds, before idle channels are timed out. The default value is 300 seconds.

      Channels are persistent logical entities that last longer than a single queue manager request, and can survive network breakages, so it might be necessary to time out channels that have been inactive for a period of time.

Connecting the terminals

The MQeInput node routes each message that it retrieves successfully to the Out terminal; if this fails, the message is retried. If the retry timeout expires (as defined by the BackoutThreshold attribute of the input queue), the message is routed to the Failure terminal; you can connect nodes to this terminal to handle this condition. If you have not connected the Failure terminal, the message is written to the backout queue.

If the message is caught by this node after an exception has been thrown further on in the message flow, the message is routed to the Catch terminal. If you have not connected the Catch terminal, the message loops continually through the node until the problem is resolved. You must define a backout queue or a dead-letter queue (DLQ) to prevent the message looping continuously through the node.

Configuring for coordinated transactions

When you include an MQeInput node in a message flow, the value that you set for the Transaction Mode property defines whether messages are received under syncpoint:

  • If you set the property to Yes (the default), the message is received under syncpoint (that is, within a WebSphere MQ unit of work). Any messages that are sent subsequently by an output node in the same instance of the message flow are put under syncpoint, unless the output node has overridden this explicitly.
  • If you set the property to Automatic, the message is received under syncpoint if the incoming message is marked persistent. Otherwise, it is not. Any message that are sent subsequently by an output node is put under syncpoint, as determined by the incoming persistence property, unless the output node has overridden this explicitly.
  • If you set the property to No, the message is not received under syncpoint. Any messages that are sent subsequently by an output node in the flow are not put under syncpoint, unless an individual output node has specified that the message should be put under syncpoint.

The MQOutput node is the only output node that you can configure to override this option.

Terminals and properties

The MQeInput node terminals are described in the following table.

Terminal Description
Failure The output terminal to which the message is routed if an error occurs.
Out The output terminal to which the message is routed if it is successfully retrieved from the WebSphere MQ Everyplace queue.
Catch The output terminal to which the message is routed if an exception is thrown downstream and caught by this node.

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 MQeInput node Description properties are described in the following table.

Property M C Default Description
Node name No No The node type, MQeInput 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 MQeInput node Default properties are described in the following table.

Property M C Default Description
Message Domain No No   The domain that is used to parse the incoming message.
Message Set No No   The name or identifier of the message set in which the incoming message is defined.
Message Type No No   The name of the incoming message.
Message Format No No   The name of the physical format of the incoming message.
Topic No Yes   The default topic for the input message.

The MQeInput node General properties are described in the following table.

Property M C Default Description
Queue Name Yes Yes   The name of the WebSphere MQ Everyplace bridge queue from which this node retrieves messages for processing by this message flow.
Trace Yes No None The level of trace required for this node. Valid values are None, Standard, Debug, and Full.
Trace Filename Yes Yes \MQeTraceFile.trc The name of the file to which trace records are written.
Transaction Mode Yes No Yes This property controls whether the incoming message is received under syncpoint. Valid values are Automatic, Yes, and No.
Use Config File Yes No Cleared If you select the check box, a configuration file is used for this node.
Config Filename Yes Yes \MQeconfig.ini The name of the configuration file to be used if the Use Config File check box is selected.
Queue Manager Name Yes Yes ServerQM1 The name of the WebSphere MQ Everyplace queue manager.

The MQeInput node Channel properties are described in the following table.

Property M C Default Description
Max Channels Yes No 0 The maximum number of channels that are supported by the WebSphere MQ Everyplace queue manager.

The MQeInput node Registry properties are described in the following table.

Property M C Default Description
Registry Type Yes Yes File Registry The type of registry information to be used. Valid values are File Registry and Private Registry.
Directory Yes Yes \ServerQM1\registry The directory in which the registry file exists (valid only if File Registry is selected).
PIN Yes Yes   The PIN that is associated with the WebSphere MQ Everyplace queue manager (valid only if Private Registry is selected).
Certificate Request PIN Yes Yes   The PIN that is used to request authentication (valid only if Private Registry is selected).
Keyring Password Yes Yes   The password that is used to see crypto keys (valid only if Private Registry is selected).
Certificate Host Yes Yes   The name of the certificate server (valid only if Private Registry is selected).
Certificate Port Yes Yes   The port of the certificate server (valid only if Private Registry is selected).

The MQeInput node Listener properties are described in the following table.

Property M C Default Description
Listener Type Yes Yes Http The adapter type for the listener. Valid values are Http, Length, and History.
Hostname Yes Yes 127.0.0.1 The hostname of the server.
Port Yes Yes 8081 The port on which WebSphere MQ Everyplace listens.
Time Interval (sec) Yes Yes 300 The WebSphere MQ Everyplace polling interval, specified in seconds.
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:17:26

ac04600_ This topic's URL is: