IBM MQ Listener

The IBM MQ Listener activity listens on a queue and when a message arrives that satisfies the configured filters it retrieves and it starts a process including the contents of the message.

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

Note: When using the Listener activity, it is important to understand the relationship between the BusinessWorks engine and IBM MQ API. The engine can stop the Listener activity or the whole application in response to commands from the administrator in TIBCO Enterprise Administrator. However, IBM MQ API does not provide any mechanism to interrupt threads, which are blocked on the get methods. So even though, the Listener activity is instructed to stop, it cannot terminate the currently executing thread, which is waiting on the get call. In a polling Listener activity, this situation is resolved when the timeout interval expires and the thread exits. However, a non-polling Listener activity never exits the get call. There are two scenarios to show this situation.
  • A message arrives after a Listener activity is stopped. In this scenario, the message is rolled back if there is a unit of work in effect. If there is no unit of work, the message is returned to the queue through a put call. Note that if the listener does not have the authority to put the message back on the queue, it attempts to put it on the dead letter queue. If there is no dead letter queue or there is an error putting the message on it, the message is lost and an error message is issued.
  • There are two listeners in the same queue after you start a new listener. Normally this is not an issue, because when a new message arrives, the first listener exits. However, if the queue is configured to be opened only by one listener, the newly started listener gets errors while connecting. It continues to attempt to connect and issue warning messages periodically. Until a message arrives, it terminates the first listener, after that, the newly started listener connects and processes the message.

There is another general scenario, which affects all process starters. If the Listener activity receives a number of messages and creates processes for them, but those processes are either running or waiting to run without adding checkpoints and the engine is shut down, those messages are lost. If it is imperative that messages are never lost, you can select the Require Client Confirmation checkbox in the General tab to ensure their integrity.

General

The General tab of the Listener activity 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 want this activity to run. This translates to 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 checkbox is selected, each thread this activity runs waits for the confirmation before getting another message from the queue. Therefore, to process messages in an absolute serial fashion, start only one instance of the listener. In this case, the number of messages processed becomes a function of how much latency exists in the activity before the confirmation.

Destination Y The name of the queue from which the message is 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 is patterned. This field is only available when the Dynamic Destination checkbox is selected.
Note: It is good practice that static queue names (queue names that do not contain a pattern) be used for listener activities. If a pattern is used for a Listener activity queue name, the name generated by the queue manager is not available until the listener creates a process that makes it impossible for a sender to know the name.
Message Content Type N Select the type of message contents:
  • Binary: the body of the message is represented as a byte array to subsequent activities in the process and is contained in the bytes element.
  • Text: the body of the message is represented as a string to subsequent activities in the process and is contained in the text element. This string is 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 parsed 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 checkbox 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 is created.
  • SHARED: other listeners can access the queue in this mode.
  • EXCLUSIVE: other listeners cannot access the queue in this mode. During execution, if the queue is opened 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 causes 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 checkbox to request the 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 waits for the confirmation before obtaining another message which imposes a limit on throughput. If serial processing of the messages is not essential, raise the value of the Instances field until the desired throughput is achieved.

If the activity fails to confirm the message, it loops and repeatedly processes the same message. To avoid this behavior, it is good practice to copy the message to an error queue and then confirm the original.

Logger Name Y Enter the name of any pre-configured logger available for the run time. Loggers are configured in an XML document referenced by the Dlogback.configurationFile runtime parameter.

Description

A short description of the Listener activity.

Multi-Message

The Multi-Message tab of the Listener activity contains the following fields:

Field Module Property? Description
Multi-Message Support N Two options are supported:
  • None
  • BatchGroup

If BatchGroup is selected, an activity is started by a listener to operate in the batch mode that contains multiple InteractionOutput nodes, each representing one message in the batch. You can determine the number of discrete messages to be included in the batch with the Batch Size field enabled. When None is selected, the Listener activity processes a single message at one time from the queue.

The main use for BatchGroup mode is to process an entire logical message in a single job.

Note: If the Require Client Confirmation checkbox is selected for a batch, the entire batch is confirmed when the Confirm activity runs. 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 1 to 100 to control the size of the batches retrieved by this listener.
Batch Delay Interval Y

When Required Client Confirmation is enabled and the batch is incomplete, the listener waits for a specified time interval. This time interval is called Batch Delay Interval. After the time interval is over, the listener confirms the batch messages even if the batch is incomplete.

If the batch delay interval is set to 0, the listener waits for an unlimited duration to complete a batch.

Unit: seconds

Valid range: 0 to 120

Default: 0

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 are created. To process incomplete logical messages, do not select this field. This option requires that the queue be indexed, otherwise, it is disabled dynamically at run time.
Explicit Commit N Every attempt is made within the plug-in to avoid unnecessary commits because of the overhead involved. However, you might select this checkbox 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 checkbox protects you from removing a message from the queue only to fail while processing the contents. Message contents can cause failures if, for example, the encoding or character set is inappropriate 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 syncpoint or not. Because of the cost of syncpoint operations, every effort has been made to avoid them. If the activity requires confirmation or uses multiple messages, a sync is required.
Poison Msg Detection N Select this checkbox to turn on poison message detection. If the Listener activity processes a message where the backout count is greater than the poison message threshold, the message is not processed but is moved to the designated poison message queue. This prevents the Listener activity from looping on a message that cannot be confirmed. Note that this checkbox is only available after you select the Require Client Confirmation checkbox and click None from the Multi -Message Support area in the Listener activity.
Poison Msg Threshold Y Enter the backout count at which a message is considered poison. If the backout exceeds this value, it is moved to the poison message queue.
Poison Msg Queue Y Enter the queue to which poison messages are moved.

Advanced

The Advanced tab of the Listener activity contains the following fields:

Field Module Property? Description
Sequence Key N This field can contain an XPath expression that specifies which processes are required to run, and in which order. Process instances with sequencing keys that evaluate the same value are executed sequentially in the order the process instance is created.

See the TIBCO ActiveMatrix BusinessWorks documentation 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 Enterprise 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 in the queue they are processed without an intervening polling interval, thus diminishing application latency.

When cleared, the activity waits forever in the queue, processing messages as they arrive. If the queue manager connection fails, the activity attempts to reconnect based on the reconnection interval. If the listener is not polling, it is doing an unbounded get on the queue, and the listener does so even after the application is set to stop using the administrator or shell command. To release the connection and close the destination, you must stop the appNode on which this application is running. This also means that if you redeploy the application without recycling the appNode, the connections from the previous deployment persist until the node is recycled. This is because there is no safe way to interrupt an IBM MQ native Java API get method.

Note: A poor choice of polling interval and polling timeout values might 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 checkbox is selected, this is the interval at which a new polling cycle is initiated.

Specify the time in milliseconds.

Valid range: 100 to 1000000

Default: 1000
Polling Timeout Y If the Enable Polling checkbox is selected, this is the timeout value for each individual listen. The value specified here must be significantly smaller than the polling interval. This minimizes the number of concurrent connections to the queue and reduces the processing resources needed.

Specify the 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 checkbox is cleared. If the Enable Polling checkbox 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 example), this value is the number of milliseconds between reconnection attempts.

Valid range: 2000 to 1000000

Default: 10000
Filter Encoding N This field specifies the encoding of the values provided in the Correlation Id, Message Id, and Group Id fields. The Filter Encoding field provides three types of values: text, base64, and hexbin.

When this field is set to either base64 or hexbin, the values of the three Id fields are transformed appropriately to form a binary filter as follows.

For example, a valid base64 filter is bzkMF27syhmb37nm8kPQojEupbpNVJHm and a valid hexbin filter is 6f390c176eecca199bdfb9e6f243d0a2312ea5ba4d5491e6.

Note that you do not use the prefix "0x" with the hexbin filter.

Correlation Id Y The Listener activity instructs the queue manager to filter the request based on this correlation ID. Only messages with the same ID are accepted.
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.
Group Id Y The Listener activity instructs the queue manager to filter the request based on the specified group ID. Only messages with the same group ID are accepted.
Application Properties N 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 MQ documentation for property types supported by the level of client you have installed.

Note: A failure to observe cardinality results in errors, processing the input or output schema.

Property Control N Select one of the following settings:
  • AS_Q_DEF
  • COMPATIBILITY
  • IN_HANDLE
  • FORCE_MQRFH2

After selecting one of these options, you can use the Listener activity to inter-operate with various versions of IBM MQ applications. Which option to use varies depending on the sending application. See the section entitled "MQGMO message property option setting" in the IBM MQ documentation for detailed information.

Conversations

You can use the Conversations tab of the Listener activity to initiate or join a conversation.

Conversations receive messages after the creation of a process instance, which is initiated or joined by an activity. This activity can be used to initiate a conversation. Click the Add New Conversation icon to initiate a conversation. For more details regarding conversations, see TIBCO ActiveMatrix BusinessWorks Application Development.

Output

The following table lists the output items for the Listener activity:

Output Item Module Property? Description
Batch N If BatchGroup in the Multi-Message tab is selected, this node is present and contains 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 to output.
  • destination: to document the destination for this message. If the queue is dynamic, the generated name is reported here.
  • destqmgr: if the message is routed through a remote queue manager, document the name of the destination queue manager.
  • correlationId: to document the message correlation ID, if any.
  • messageId: to document the message ID.
  • groupId: to document the group ID used for this message, if any.
  • characterSet: to document the character set the queue manager uses to process this message.
  • alternateUserId: to document the alternate user ID used in this operation, if any.
  • 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 the application that puts 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

  • putApplicationName: the name of the application that puts the message.
  • userId: the effective user ID used to connect to the queue manager.
  • replyToQueueName: the name of the queue to which a reply is sent. If the type of the message is Request, then this is the name of the queue that the application sends the reply message.
  • replyToQmgrName: 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 use standard names (these names are prefixed by the MQ text) or application-generated names. If this message originates from the ActiveMatrix BusinessWorks Plug-in for IBM MQ application, 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 is used when the message is sent.
  • priority: the priority (from 1 to 9) with which the message is sent.
  • reportOptionPan: reflects the value of the Positive Acknowledgment bit of the report field. This field is an application-only field and is not acted upon by the queue manager.
  • reportOptionNan: reflects the value of the Negative Acknowledgment bit of the report field. This field is an application-only field and is not acted upon by the queue manager.
  • report: this is the report options field for the message. If reports are requested for the message, the relevant bits are 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 the processing of fields is mapped by a message body schema. For specific values, see the MQMessage encoding field in the IBM MQ documentation.
  • messageType: an 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 is 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 is placed into the queue.
  • groupStatus: to indicate whether the message is part of a logical message. It can contain any of the following:
    • MSG_IN_GROUP
    • MSG_NOT_IN_GROUP
    • MSG_LAST_IN_GROUP
dynamicProperties  
  • dynamic property: these properties are the same as those mapped through the appProperties node with the exception that no special schema is required to map them. A dynamicProperties node is created for each property in the message which was not mapped by the appProperties schema mechanism. If no appProperties schema is in place, all properties are dynamic.
  • name: the name of the property.
  • value: the string type value of the property.
  • type: the type for the property. The valid types are "string", "boolean", "short", "integer", "long", "float", "double", and "byte".
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 when Binary is selected in the Message Content Type area.

text N If the activity is configured to use text messages then this node is present instead of the bytes field. The contents of the message are decoded into a string using the Java default encoding and presented here.

This field is only displayed when Text is selected in the Message Content Type area.

responsetimemillisec N The time, in milliseconds, that the listener takes to receive this message. It is measured from when the listener starts listening to when it finishes 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 that are missing or not present in the schema are not shown here.
messageFields N Contains the message body formatted using Schema in the Message Content Type field of the General tab. Each field in the schema is mapped here.

This field is displayed for schema-based messages only.

Fault

The Fault tab lists exceptions that occur in the Listener activity:

Error Schema Element Data Type Description
msg String The ActiveMatrix BusinessWorks Plug-in for IBM MQ error message.
msgCode String The ActiveMatrix BusinessWorks Plug-in for IBM MQ error code.
mqCompCode String If the message originates as an IBM MQ API exception, then that exception's completion code is here.
mqReasonCode String If the message originates as an IBM MQ API exception, then that exception's reason code is here.
mqErrorCode String If the message originates as an IBM MQ API exception, then that exception's reason code is here.