IBM MQ Subscriber

The Subscriber activity listens on a topic or an administratively defined subscription and starts a process that provides the contents of the message.

The subscriber can poll a topic based on interval and timeout values, or it can wait indefinitely. Regardless of which mode it is in, when messages arrive they are each processed immediately with no intervening interval time. When polling is enabled, messages published to the subscribed topic are not lost during the interval when the subscriber is not actively listening because the subscriber exists for the duration and is not created and destroyed across intervals. However, this does not necessarily apply during error recovery or lost connection scenarios.

The topic string is composed of two optional parts:
  • An administratively defined topic. This option implies a root topic string defined on the server.
  • A dynamic topic string which is concatenated to the topic string for the defined topic, if one is specified.

If neither of these fields is provided but an existing durable subscription is specified, the activity subscribes to the durable subscription.

The queue manager inserts the forward slash (/) as necessary to compose a well formed topic string.

While the listener is active, a temporary dynamic subscription is created (in the queue manager) so that all messages appropriate for the topic are routed there. This subscription ceases to exist when the listener is stopped, or in error recovery. To avoid missing messages destined for the topic, you can enable the Durable Subscription option to have the subscription persisted indefinitely in the queue manager using the name provided. Durable subscriptions accumulate messages even when there are no listeners, much like a queue would.

Note: When using the Subscriber activity, it is important to understand the relationship between the BusinessWorks engine and IBM MQ API. The engine can stop the Subscriber 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 Subscriber activity is instructed to stop, it cannot terminate the currently executing thread, which is waiting on the get call. In a polling Subscriber activity, this situation is resolved when the timeout interval expires and the thread exits. However, a non-polling Subscriber activity never exits the get call. There are two scenarios to show this situation.
  • A message arrives after a Subscriber activity is stopped. In this scenario, the message is rolled back.
  • There are two subscribers in the same queue after you start a new subscriber. Normally this is not an issue, because when a new message arrives, the first subscriber exits. However, if the subscriber is using a durable subscription, only one thread can use this destination at a time, and the second subscriber fails to connect. It continues to attempt to connect and issue warning messages periodically. Until a message arrives, it terminates the first subscriber, after that, the second started subscriber connects and processes the message.

There is another general scenario, which affects all process starters. If the Subscriber 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 Subscriber 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 Choose the connection resource which associates this activity with the queue manager that has access to the desired topic.

Click to select a usable connection for the activity.

Destination Y The name of the administratively defined portion of the topic string. If a topic name is specified, the topic string associated with that name in the queue manager forms the root or left-most portion of the topic string.
Wildcard Scheme N IBM MQ supports two wild card schemes:
  • Topic: associated with current queue managers.
  • Char: associated with version 6 and earlier of IBM MQ.

Either scheme can be used. Consult the IBM MQ documentation for information about these schemes.

Topic Dynamic Y Enter the dynamic portion of the topic string here. This field can contain the entire topic string or only the right-most portion of it, depending on whether it is to be used with an administratively defined topic.
Durable Subscription N When selected, the subscription created by this subscriber is durable. Durable subscriptions survive subscriber and queue manager restarts, and accumulate messages until they are explicitly deleted.
Subscription Name Y Enabled if the Durable Subscription checkbox is selected. This is the name of the permanent subscription.

A subscriber can be started using only the durable subscription name. If the subscription exists, no topic string or dynamic topic are necessary.

Message Content Type N The following types of message content are supported:
  • Binary: the bytes field in the output schema is provided and contains a byte array representing the messages contents.
  • Text: the text field in the output schema is provided and contains a string composed by decoding the message's byte array using the default Java encoding.
  • 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 Provide the schema to be used in the Output tab, and at run time to decode the contents of this message.
New Publications Only N Select the New Publications Only checkbox for non-durable subscriptions where you do not want to receive the last message published with the Retain Message option. In essence, this is a way of opting out of the application state message.
Fail If Quiescing N Select the Fail If Quiescing checkbox to prevent this subscriber from holding up a queue manager quiesce operation. If the queue manager does terminate, the activity attempts to reconnect indefinitely.
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 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 an absolute limit on the throughput. If serial processing of the messages is not essential, raise the value of the Instances field until either the worker threads are 100% busy or the desired throughput is achieved.

If the activity fails to confirm the message, it loops and repeatedly processes the same message.

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

Description

A short description for the Subscriber activity.

Advanced

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

Field Module Property? Description
Sequence Key N This field can contain an XPath expression that specifies which processes can 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 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 wizard of TIBCO Enterprise Administrator, and it is also available in the $_processContext process variable.
Enable Polling N When selecting the Enable Polling checkbox, the activity instantiates a connection to the queue manager and opens the topic. It then periodically issues timed gets on the topic 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 available, they are processed without an intervening polling interval, thus diminishing application latency.

When clearing the Enable Polling checkbox, the activity waits indefinitely on the topic, 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 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 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 value in the Polling Interval field. 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 topic.

This setting is used only when polling is disabled. If polling is not enabled, the listener 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

Application Properties N If the messages expected on this topic contain application specific topics, a shared schema resource must be created to represent those properties and it has to be mapped here. Messages which contain any or all of these properties have them provided as input to the process created by this starter. 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 Subscriber 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 Subscriber 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 Subscriber activity:

Output Item Module Property? Description
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 have been mapped from the received message.
  • destination: to document the destination for this message. This field contains the complete topic string for the message.
  • destqmgr: to document the remote queue manager specified in the input schema.
  • topicdynamic: to override the Topic Dynamic field from the General tab. This string forms the dynamic portion of the fully resolved topic name.
  • correlationId: to document the message correlation ID. In most cases, this is an internal queue manager value and is not available for filtering purposes.
  • messageId: to document the message ID.
  • 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 that supports work done as a result of the message to be appropriately billed.
  • applicationIdData: application ID data. This is application data was provided by sender of the message.
  • 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
  • putApplicationName: the name of the application that puts the message, if one is provided.
  • 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 message is a request.
  • replyToQmgrName: if this message arrived by way of a remote queue manager specification, this field documents the queue manager to which this subscriber is connected.
  • format: a name that describes the nature of the data in the message.
  • 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. Reflects the report options in effect for this message.
  • 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 is used when processing of fields mapped by a message body schema. For specific values, see the MQMessage encoding field in the IBM MQ documentation.
  • messageType: enumerated value indicating the message type:
    • 8 is Datagram.
    • 2 is Reply.
    • 4 is Report.
    • 1 is Request.
  • backoutCount: the number of times this message is 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.
  • putDateTime: the time that the message is placed onto the topic.
  • 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 exactly 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. Note that the publish and subscribe mechanisms in IBM MQ uses message properties in the implementation, you can see the property mqps.Top and possibly others on all publications.
  • 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 This field contains a text representation of the bytes in the message body as converted using the default Java encoding.

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

responsetimemillisec N This field records the time, in milliseconds, that it takes to start the IBM MQ get API call until the event context for the new activity is created.
appProperties N This field maps the application properties present in the received message to the schema attached to the activity. Properties which are missing or not present in the schema are not shown here.

The field is only displayed if an application properties schema is configured for the activity.

messageFields N Contains the message body formatted using Schema in the Message Content Type field of the General tab.

This field is displayed for schema-based messages only.

Fault

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

Error Schema Element Data Type Description
msg String The TIBCO ActiveMatrix BusinessWorks Plug-in for IBM MQ error message.
msgCode String The TIBCO 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 error code is here.