MQeInput node

Attention: The use of message flows that contain MQeInput and MQeOutput nodes in WebSphere Message Broker Version 6.0 is deprecated. The behavior that is described here is intended only for when you are deploying from Version 6.0 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 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 containing this node.

Message flows that handle messages 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 that messages are received. For example, you can indicate that a message is to be processed under transaction control.

When you deploy message flows containing 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 flows must all specify the same WebSphere MQ Everyplace queue manager name. You get an error on deploy if you do not meet this restriction.

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 have 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 Event Broker. This is compatible with later versions of WebSphere MQ Everyplace. Clients using later versions of WebSphere MQ Everyplace, for example Version 2.0, work correctly when connected to this node, although additional functionality 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 created using Version 1.2.6. Similarly, the client must use its level of the code when creating a queue manager.

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 one of these other input nodes.

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 requiring water, so, using his PDA and a Global Satellite Navigation link, he sends a message to an MQeInput node. 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

You can 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. Right-click the node in the editor view and click Properties. The node's default properties are displayed in the properties dialog.

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 MQeInput node as follows:

  1. Select General in the properties dialog navigator and complete 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 one of:
      • None. This is the default setting. 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 to be 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 subsequently sent by an output node is determined by the incoming persistence property, unless the output node has explicitly overridden transactionality.
      • If you select Yes, the incoming message is received under syncpoint. Any derived messages subsequently sent by an output node in the same instance of the message flow are sent transactionally, unless the output node has explicitly overridden transactionality.
      • If you select No, the incoming message is not received under syncpoint. Any derived messages subsequently sent by an output node in the 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 dialog.

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

      • 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 on the properties dialog 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 is not related to the queue manager of the broker to which you deploy the message flow containing 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 included in every message flow that you deploy to the same broker.

  2. Select Channel in the properties dialog navigator and set the maximum number of channels supported by WebSphere MQ Everyplace in Max Channels. The default is zero, which means that there is no limit.
  3. Select Registry in the properties dialog navigator and complete the following properties:
    1. Select the type of registry from the drop down list in the Registry Type property. You can choose one of the following:
      • 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 require.
    2. In Directory, specify the directory in which the registry file is located. This 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:
      • Specify a PIN for the associated queue manager. For further details, refer to the WebSphere MQ Everyplace documentation.
      • Specify a Certificate Request PIN for authentication requests. For further details, refer to the WebSphere MQ Everyplace documentation.
      • Provide a Keyring Password to be used as a seed for the generation of crypto keys. For further details, refer to the WebSphere MQ Everyplace documentation.
      • In Certificate Host, specify the name of the certificate server that WebSphere MQ Everyplace uses for authentication. For further details, refer to the WebSphere MQ Everyplace documentation.
      • In Certificate Port, specify the number of the port for the certificate server that WebSphere MQ Everyplace uses for authentication. For further details, refer to the WebSphere MQ Everyplace documentation.
  4. Select Listener in the properties dialog navigator and complete the following properties that define the connection type for WebSphere MQ Everyplace:
    1. In Listener Type, select the adapter type that you want to use from the drop down list. The default 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 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 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.

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

  5. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  6. Click Apply to make the changes to the MQeInput node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Connecting the terminals

MQeInput 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 it to Yes (the default), the message is received under syncpoint (that is, within a WebSphere MQ unit of work). Any messages subsequently sent by an output node in the same instance of the message flow are put under syncpoint, unless the output node has explicitly overridden this.
  • If you set it to Automatic, the message is received under syncpoint if the incoming message is marked persistent. Otherwise, it is not. Any message subsequently sent by an output node is put under syncpoint, as determined by the incoming persistence property, unless the output node has explicitly overridden this.
  • If you set it to No, the message is not received under syncpoint. Any messages subsequently sent 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 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 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 Whether the incoming message is received under syncpoint. Valid values are Automatic, Yes, and No.
Use Config File Yes No Cleared Use a configuration file for this node. If you select the check box, this action is performed.
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 supported by the WebSphere MQ Everyplace queue manager.

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

Property M C Default Description
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 associated with the WebSphere MQ Everyplace queue manager (valid only if Private Registry is selected).
Certificate Request PIN Yes Yes   The PIN used to request authentication (valid only if Private Registry is selected).
Keyring Password Yes Yes   The password 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 Yes Yes 300 The WebSphere MQ Everyplace polling interval, specified in seconds.

The MQeInput 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.