WebSphere MQ Listener

The listener can poll a queue based on interval and a timeout values, or it can wait indefinitely on a queue. Regardless of which mode it is in, when messages arrive on the queue they are each processed immediately with no intervening interval time.

General

The General tab contains the following fields.

Field	Module Property ?	Description
Name	N	The name to be displayed as the label for the activity in the process.
Connection	Y	The connection resource which connects this activity with the queue manager that has access to the desired queue.
Instances	Y	Enter the number of instances of the queue listener you wish this activity to run. This translates exactly the number of threads and connections to the Queue Manager created by this activity. The default is 1 and the maximum is 64. If the Require Client Confirmation check box is selected below, each thread this activity runs will wait for the confirmation before getting another message from the queue. Therefore, to process messages in an absolute serial fashion, only one instance of the listener should be started. In this case, the number of messages processed becomes a function of how much latency exists in the activity prior to the confirmation.
Destination	Y	The name of the queue from which the message will be retrieved.
Dynamic Destination	N	A flag that enables the creation of a dynamic queue. When selected, the Dynamic Destination Model field is enabled.
Dynamic Destination Model	Y	Provide the name of the model queue after which this dynamic queue will be patterned. This field is only available if the above Dynamic Destination check box is selected. Note: It is recommended that static queue names (queue names that do not contain a pattern) be used for listener activities. Should a pattern be used for a Listener activity queue name, then the name generated by the queue manager is not available until the listener creates a process which makes it impossible for a sender to know the name.
Message Content Type	N	Select the type of message content: Binary: The body of the message will be represented as a byte array to subsequent activities in the process and will be contained in the `bytes` element. Text: The body of the message will be represented as a string to subsequent activities in the process and will be contained in the `text` element. This string will be converted from the bytes in the message using the `characterSet`element in effect for this message. Schema: If the message has been written using the MQMessage read/write API calls, it can be rendered here by providing a schema resource that conforms to the schema of the message.
Message Body Fields	Y	If the message has been written using the MQMessage read/write API calls, use this field to map a schema conforming to the message body.
Fail If Quiescing	N	Select the Fail If Quiescing check box to prevent this listener from holding up a queue manager quiesce operation. If the queue manager does terminate, the activity attempts to reconnect indefinitely.
Access Mode	N	Select the access mode for the queue: QDEFAULT: It accepts the access mode established when the queue was created. SHARED: It allows other listeners to access the queue. EXCLUSIVE It does not allow other listeners to access the queue. During execution, if the queue is open by another application then the activity fails.
GMO Convert	N	Causes the get message option MQGMO_CONVERT to be used for this get operation. It will cause the queue manager to convert string and numeric fields using the `characterSet` and `encoding` elements before the data is copied to the message buffer.
Require Client Confirmation	N	Select the Require Client Confirmation check box to request explicit confirmation of a received message. The confirm activity can be used to confirm the message’s arrival and remove it from the queue. The Plug-in uses the queue manager's Syncpoint capability to ensure that the message is only removed from the queue if it is confirmed. Note: The activity will wait for the confirmation before obtaining another message which imposes an absolute limit on the throughput. If serial processing of the messages is not essential, raise the Instances parameter until either the worker threads are 100% busy or the desired throughput is achieved. If the activity fails to confirm the message, it will loop and repeatedly process the same message.
Logger Name	Y	Enter the name of any pre-configured logger available to the runtime. Loggers are configured in an XML document referenced by the Dlogback.configurationFile runtime parameter.

Description

Provide a short description for the activity.

Multi-Message

The Multi-Message tab contains the following fields.

Field	Module Property ?	Description
Multi-Message Support	N	Two options are supported: None BatchGroup If BatchGroup is selected, an activity started by a listener to operate in batch mode that contains multiple `InteractionOutput` nodes, each representing one message in the batch. The Batch Size field will be enabled allowing you to determine the number of discrete messages to be included in the batch. When None is selected, the Listener activity processes a single message at one time from the queue. The main improvement that Batch Mode offers is all messages in the batch are committed by a single call thus eliminating continual round trips which reduces network traffic and latency involved with committing each message individually. The size of the batch for a Put activity is determined by the number of nodes in the input schema. Note: If explicit client confirmation is selected for a batch, the entire batch will be confirmed when the confirmation activity runs. Enabling Batch Mode eliminates the confirmation of individual messages, so if an error is detected while processing a message, the entire batch must be reprocessed.
Batch Size	Y	If BatchGroup is selected, this field becomes enabled. Enter valid inputs range from 2 to 100 to control the size of the batches retrieved by this listener.
Complete Message	N	Enable this field to cause the listener to only process the first member of a logical message when all the members of the logical message have been written to the queue. This must be deselected when processing incomplete logical messages and when processing huge logical messages one message at a time.
Get Ordered	N	Select this field to cause logical messages to be processed in the order in which they were created. To process incomplete logical messages, you should not select this field. This option requires that the queue be indexed, otherwise it will be disabled dynamically at runtime.
Explicit Commit	N	Every attempt is made within the plug-in to avoid unnecessary commits due to the overhead involved. However you might select the check box to force the creation of a unit of work and subsequent commit. The commit happens after any application properties and message body fields have been processed, so selecting this check box protects you from removing a message from the queue only to fail while processing the contents. Message contents can cause failures if, for instance, the encoding or character set is in appropriate for the data, or the schema used to process the message is in error.
Syncpoint Used	N	This field is not a configuration parameter, but is a status indication of whether the activity is configured to require a sync-point or not. Because of the cost of sync-point operations every effort has been made to avoid them. If the activity requires a confirmation or uses multiple messages a sync will be required.

Advanced

The Advanced tab contains the following fields.

Field	Module Property?	Description
Sequence Key	N	This field can contain an XPath expression that specifies which processes should run, and in which in order. Process instances with sequencing keys that evaluate to the same value are executed sequentially in the order the process instance was created. See TIBCO ActiveMatrix BusinessWorks Process Design Guide for more information about controlling the execution order of process instances and about XPath expressions.
Custom Job Id	N	This field can contain an XPath expression that specifies a custom ID for the process instance. This ID is displayed in the View Service dialog of TIBCO Administrator, and it is also available in the $_processContext process variable.
Enable Polling	N	When selected, the activity instantiates a connection to the queue manager and opens the queue. It then periodically issues timed gets on the queue where the timeout value is equal to the polling timeout and the period between gets is equal to the polling interval. However, if there are multiple messages on the queue they are processed without an intervening polling interval, thus diminishing application latency. When cleared, the activity waits forever on the queue, processing messages as they arrive. If the queue manager connection fails the activity attempts to reconnect based on the reconnection interval. Note: A poor choice of polling interval and polling timeout values could impose a high overhead on the engine as well as the queue manager to which the activity is connected. Use values here which take into account the latency in the network between this activity and the queue manager, as well as the processing demands you are willing to place on that queue manager.
Polling Interval	Y	If the Enable Polling check box is selected, this is the interval at which a new polling cycle is initiated. Specify time in milliseconds. Valid range: 100 to 1000000 Default: 1000
Polling Timeout	Y	If the Enable Polling check box is selected, this is the timeout value for each individual listen. The value specified here should be significantly smaller than the Polling Interval. This minimizes the number of concurrent connections to the queue and reduces the processing resources needed. Specify time in milliseconds. Valid range: 10 to 1000000 Default: 1000
Reconnection Interval	Y	The length of time, in milliseconds, that the listener waits between attempts to reconnect to the queue. This setting is used only when the Enable Polling check box is cleared. If the Enable Polling check box is cleared, the Listener activity listens indefinitely on the queue. However, if an error occurs and the queue manager is subsequently unavailable (shut down for instance), this value is the number of milliseconds between reconnection attempts. Valid range: 2000 to 1000000 Default: 10000
Correlation Id	Y	The Listener activity instructs the queue manager to filter the request based on this correlation ID. Only messages with exactly the same ID are accepted. Note: WebSphere MQ uses byte arrays for correlation IDs. However, it is not possible to provide a byte array as a configuration parameter. When filtering a queue this way, be sure to use a clear text correlation ID on the application that did the put.
Message Id	Y	The Listener activity instructs the queue manager to filter the request based on the specified message ID. Note: In contrast to correlation IDs, message IDs are always provided. If the listener does not explicitly state a message ID, it accepts any message. If an ID is provided, the listen is filtered for that message ID.
Application Properties	Y	Select the Application Properties resource to be used to map the output of this get. Application properties are similar to regular message header fields except that the name and type of the fields can be determined by a predefined schema. If the received message contains properties, they are mapped according to this schema. To use application properties create a generic XML schema composed of a node with simple elements inside it and map that schema to this field. See the IBM WebSphere documentation for property types supported by the level of client you have installed. Note: A failure to observe cardinality will result in errors processing the input or output schema.

Output

The Output tab contains the following fields.

Field	Module Property?	Description
Batch	N	If BatchGroup in the Multi-Message Support area is selected, this node will be present and will contain an `InteractionOutput` node for each message retrieved as part of this batch.
InteractionOutput	N	The root node for all the output provided by the activity.
mqproperties	N	The node containing all the message header fields (plus the destination override) which are relevant on output. `destination`: To document the destination for this message. If the queue was a dynamic queue, the generated name is reported here. `destqmgr`: If the message was routed through a remote queue manager, documents the name of the destination queue manager. `correlationId`: To document the message correlation ID, if any. `messageId`: To document the message ID. `characterSet`: To document the character set the queue manager used to process this message. `alternateUserId`: Specify a userid to be used as an alternate user for this operation only. The user used in the connection resource must have the Alternate Userid Authority in order to use this field. `accountingToken`: The accounting token provided by the sending application. `applicationIdData`: Application ID data as provided by the sending application. `applicationOriginData`: Additional information about the origin of the message provided by the sender of the message. `putApplicationType`: The type of application that put the message. Documented enumerations are: MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01 MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03 MQAT_MVS MQC.MQAT_MVS 0X02 MQAT_OS2 MQC.MQAT_OS2 0X04 MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06 MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0A MQAT_VMS MQC.MQAT_VMSQ 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14 MQAT_NO_CONTEXT `putApplicationName`: The name of the application that put the message. `userId`: The effective user ID used to connect to the queue manager. `replyToQueueName`: The name of the queue to which a reply should be sent. If the type of the message is Request, then this is the name of the queue that the application should sent the reply message to. `replyToQueueMgrName`: The name of the remote queue manager to be used when processing any reply or report message. `format`: A name that describes the nature of the data in the message. The sender of the application can used standard names (these names are prefixed by the text MQ) or application generated names. If this message originated from a TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ, then this field contains an empty string. `expiry`: The expiration time (in tenths of a second), after which the message is eligible to be discarded by the queue manager. This contains whatever value was used when the message was sent. `priority`: The priority (from 1 to 9) with which the message was sent. `reportOptionPan`: This is the Positive Acknowledgment report field and is provided by the sending application. This report field is not acted upon by the queue manager. `reportOptionNan`: This is the Negative Acknowledgment report field and is provided by the sending application. This report field is not acted upon by the queue manager. `report`: This is the report options field for the message. If reports were requested for the message, the relevant bits will be present here. `encoding`: This is the `encoding` element for the message and it specifies the representation used for numeric values in the application message data. This applies to binary, packed decimal and floating point data. This `encoding` element is used when processing of fields mapped by a message body schema. For specific values see the MQMessage encoding field in the WebShere MQ documentation. `groupId`: To document the group ID used for this message, if any. `messageType`: Enumerated value indicating the message type. Where: 8 is Datagram. 2 is Reply. 4 is Report. 1 is Request. `backoutCount`: The number of times this message was backed out before being committed. `feedback`: If the message was a Report message, this field defines the nature of the report. Defaults to 0 for non report messages. `version`: To document the version of the message. This Plug-in supports type 2 messages only. `putDateTime`: The time that the message was placed onto the queue. `groupStatus`: To indicate whether the message is part of a logical message. It can contain: MSG_IN_GROUP MSG_NOT_IN_GROUP MSG_LAST_IN_GROUP
bytes	N	The output body of the message. Typically, this byte array is to be mapped as input to a Data Conversion Plug-in parse activity. This field is only displayed if the activity is configured to use the Binary mode.
text	N	If the activity is configured to use text messages then this node will be present in the `bytes` field. The contents of the message will be decoded into a string using the Java default encoding and presented here. This field is only displayed if the activity is configured to in the Text mode.
responsetimemillisec		The time, in milliseconds, that the listener took to receive this message. It is measured from when the listener started listening to when it has finished creating the event context passed to the remaining activities in this process.
appProperties	N	This field maps the application properties present in the received message to the schema attached to the activity and only displays if application properties are mapped on the Advanced tab. Properties which are missing or not present in the schema are not shown here.
messageFields	N	Contain the message body formatted using Schema in the Message Content Type list of the General tab. Appear for schema based messages only.

Fault

The Fault tab lists exceptions that are thrown by this activity.

Error Schema Element	Data type	Description
msg	string	The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ error message.
msgCode	string	The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ error code.
mqCompCode	string	If the message is originated as a WebSphere MQ API exception, then that exception's completion code will be here.
mqReasonCode	string	If the message is originated as a WebSphere MQ API exception, then that exception's reason code will be here.