IBM WebSphere MQ Output Adapter

Contents

Introduction
IBM MQ Middleware Dependencies
Adapter Properties
Using the Adapter in a StreamBase Application
Typechecking and Error Handling
Suspend and Resume Behavior
Related Topics

Introduction

The TIBCO StreamBase® Output Adapter for IBM MQ Series allows a StreamBase application to publish messages to an IBM WebSphere MQ server. Each tuple enqueued to the adapter results in a message sent to the server. The adapter is embedded in the StreamBase application. The adapter can be configured to publish messages via topics or an MQ queue.

The adapter's input port can have at most one string field, which holds the message to be sent to the WebSphere MQ server. In addition, the adapter can be configured to send XML messages, in which case the input port may have one or more top-level tuple fields, each is which is used to send an XML message with a specific top-level XML element. The XML message hierarchy is represented by list and nested tuple fields under the top-level tuple field.

The adapter provides a status output port to convey status and error information to the StreamBase application. For example, when the state of the connection to the MQ server changes, a connection status tuple is emitted from the status output port.

The adapter is configured through several properties set in the adapter's Properties view in StreamBase Studio.

IBM MQ Middleware Dependencies

You must obtain the required IBM MQ Java libraries directly from IBM. The easiest way to make the IBM MQ API accessible to StreamBase is to copy the required API JARs into the StreamBase installation in the lib/ext directory.

If copying the JAR files to lib/ext is impractical, then for running IBM MQ adapter applications in StreamBase Studio, you must add the IBM MQ JARs to the Java Build Path. For running IBM MQ adapter applications from the command line, you must add the IBM MQ API JARs to the server's CLASSPATH, either by setting an environment variable, or via the <java-vm> element of the server configuration file.

Obtain the following required IBM MQ JAR files from an IBM MQ Series 7.0 installation, or directly from IBM:

com.ibm.mq.commonservices.jar

com.ibm.mq.headers.jar

com.ibm.mq.jar

com.ibm.mq.jmqi.jar

com.ibm.mq.pcf.jar

connector.jar

Adapter Properties

Property	Description
Bindings Mode	If enabled, the adapter connects directly to a local queue manager rather than communicating through a network. When enabled, the Host Name, Port Number, and Channel Name controls are disabled.
Host Name	The hostname or IP address of the IBM WebSphere MQ server.
Port Number	The TCP port number of the MQ server.
User ID	The IBM WebSphere MQ user name, if your site requires authentication when connecting to the MQ server.
Password	Password for User ID
Queue Manager	The MQ queue manager name.
Use Topics	If enabled, the adapter publishes messages via topics. Otherwise, it publishes messages via the configured MQ queue.
Default Topic	When configured to use topics, the topic to publish messages to if not overridden by the input tuple's topic field.
Topic Field Name	The name of the input port field used to override the default topic value. If this field is null in an enqueued tuple, the default topic is used.
Queue Name	The MQ queue name.
Reply To Queue Manager	The MQ queue manager name to which responses should be sent. Can be overridden using the corresponding field in the metadata tuple.
Reply To Queue Name	The MQ queue name to which responses should be sent. Can be overridden using the corresponding field in the metadata tuple.
Channel Name	The MQ channel name.
Unicode Encoding	Specifies which of three encoding formats are used to encode Unicode payloads: `UTF-16`, `UTF-16 Big Endian`, or `UTF-16 Little Endian`.
Generate XML from Tuple Fields	If enabled, one or more top-level tuple fields may be present in the adapter's input port schema. When a tuple is enqueued on this port, the adapter finds the non-null input field (at most one non-null input field is allowed), and if the field is of type tuple, walks the field to populate the XML message. If the field is of type string, the message is sent verbatim.
Date/Time Format	Used when parsing XML to convert date and time XML elements to timestamps. The format of the format string is described in the `java.text.SimpleDateFormat` class described in the Oracle Java Platform SE reference documentation. Typical format string values include `yyyyMMdd` and `yyyyMMdd HH:mm:ss`.
Metadata Field Name	The name of an optional metadata tuple field in the adapter's input schema. Use this field to provide one or more specific metadata values in outgoing MQ messages.
Set Identity Context	If enabled, the metadata input schema may contain the following additional fields to set the outgoing MQ message's identity context: `AccountingToken`, `ApplicationIdData`, `UserId`.
Send Publish Acknowledgement	If enabled, the adapter emits a tuple on its status port with `type=Messsage` and `action=Published` each time an MQ message is successfully queued to the MQ queue.
Put Messages Asynchronously	If enabled the messages will be put onto queues and topics asynchronously.
Reconnect Interval	The time, in seconds, to wait between attempts to connect to the Wall Street Systems server. The valid range is 1 to 60, inclusive.
Quick Connection-Down Detection	If enabled, the adapter polls the base queue periodically to quickly detect connection-down conditions.
SSL Cipher Suite	The cipher suite to use when connecting to an MQ sever using SSL, or blank for non-SSL connections. When using SSL connections, a truststore file is specified through JVM parameters in the server configuration file: `<param name="jvm-args" value="-Djavax.net.ssl.trustStore=/etc/truststore.jks -Djavax.net.ssl.trustStorePasswords=truststorepass -Djavax.net.ssl.keyStoreType=JKS"/>`
Log Level	Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

Using the Adapter in a StreamBase Application

This section discusses how to use the IBM WebSphere MQ output adapter in a StreamBase application. As shown in the diagram below depicting the adapter's sample application, the output adapter (MQOutput) has one no input port and one output port to communicate with the surrounding application.

The IBM WebSphere MQ Output Adapter's ports are used as follows:

Input Port 1, SendMessage: Tuples enqueued on this port cause the adapter to send messages to the MQ server. The schema of this port is derived from the upstream operator or stream and may have at most one string field and zero or more top-level tuple fields. A tuple received on the adapter's input port may have at most one non-null, top-level field.
- string field: Contains the contents of a message to be sent to the MQ server verbatim.
- optional topic string field: When using topics, contains the name of the topic to publish the message to, or null to use the configured default topic.
- tuple field(s): Allowed only when the adapter's Generate XML from Tuple Fields property is enabled. Each field contains the contents of an XML message with a specific top-level element. Hierarchy in the XML message is represented by list and nested tuple fields.
- optional metadata tuple field: This field's name must match the value specified in the adapter's Metadata Field Name property. If present, this tuple field may have one or more of the following sub-fields, each of which provides a specific metadata value:
  - AccountingToken, blob: A token that allows work done as a result of the message to be appropriately charged. This field may be present only when the Set Identity Context property is enabled.
  - ApplicationIdData, string: Used to provide additional information about the message or its originator. This field may be present only when the Set Identity Context property is enabled.
  - CharacterSet, string: The coded character set identifier of character data in the application message data. Valid values include:
    
    ASCII
    
    ISO ASCII
    
    EBCDIC
    
    Unicode
    
    UTF-8
  - CorrelationId, blob: The correlation identifier of the message.
  - Encoding, tuple: Specifies the representation used for binary, packed decimal and floating point values in the application message.
    
    Value, int: The bitmap used to specify all encoding values. TIBCO recommends leaving this field null and instead using following fields to specify the encoding:
    
    Binary, tuple: The binary encoding value.
    
    Normal, bool: True if normal (big endian) is used for binary values.
    
    Reversed, bool: True if reversed (little endian) is used for binary values.
    
    PackedDecimal, tuple: The packed decimal encoding value.
    
    Normal, bool: True if normal (big endian) is used for packed decimal values.
    
    Reversed, bool: True if reversed (little endian) is used for packed decimal values.
    
    FloatingPoint, tuple: The floating point encoding value.
    
    Normal, bool: True if normal (big endian) is used for floating point values.
    
    Reversed, bool: True if reversed (little endian) is used for floating point values.
    
    S390, bool: True if S390 (zSeries) is used for floating point values.
  - Expiry, int: The expiry time (in tenths of a second) of the message.
  - Feedback, tuple: The nature of the feedback report, used with a MQ messages of type REPORT to indicate the nature of the report.
    
    Value, int: Application-defined feedback value. Use one of the following boolean fields for IBM-defined feedback values:
    
    Activity
    
    ApplCannotBeStarted
    
    ApplTypeError
    
    ApplTypeError
    
    BufferOverflow
    
    ChannelCompleted
    
    ChannelFail
    
    ChannelFailRetry
    
    COA
    
    COD
    
    DataLengthNegative
    
    DataLengthTooBig
    
    DataLengthZero
    
    Expiration
    
    IihError
    
    LengthOffByOne
    
    MaxActivities
    
    Nan
    
    None
    
    NotDelivered
    
    NotForwarded
    
    Pan
    
    Quit
    
    StoppedByMsgExit
    
    TmError
    
    UnsupportedDelivery
    
    UnsupportedForwarding
    
    XmitQMsgError
  - Format, string: A name that indicates the nature of the data in the message.
  - GroupId, blob: This identifier of the message group to which the message belongs.
  - MessageFlags, tuple: Flags controlling the segmentation and status of the message.
    
    Value, int: The message flags bitmap. TIBCO recommends leaving this field null and instead using following boolean fields to specify the message flags:
    
    SegmentationInhibited
    
    SegmentationAllowed
    
    Segment
    
    LastSegment
    
    MsgInGroup
    
    LastMsgInGroup
  - MessageId, blob: The message identifier of the message.
  - MessageType, string: The type of the message:
    
    DATAGRAM
    
    REQUEST
    
    REPLY
    
    REPORT
  - OriginalLength, int: The original length of a segmented message.
  - Persistence, tuple: The message persistence:
    
    Value, int: The persistence bitmap. TIBCO recommends leaving this field null and instead using following boolean fields to specify the persistence:
    
    Persistent
    
    NotPersistent
    
    PersistenceAsQDef
  - Priority, int: The message priority
  - ReplyToQueueManagerName, string: The MQ queue manager name to which responses should be sent. Overrides the corresponding adapter property.
  - ReplyToQueueName, string: The MQ queue name to which responses should be sent. Overrides the corresponding adapter property.
  - Report, tuple: Specifies which report messages are required, whether the application message data is to be included in them, and also how the message and correlation ID in the report or reply are to be set.
    
    Value, int: The bitmap used to specify all report values. TIBCO recommends leaving this field null and instead using following fields to specify the report value:
    
    Exception, tuple: Specifies whether application data is included in exception reports.
    
    Basic, bool: True if basic information is included in exception reports.
    
    Data, bool: True if partial application data is included in exception reports.
    
    FullData, bool: True if partial application data is included in exception reports.
    
    Exception, tuple: Specifies whether application data is included in exception reports.
    
    Basic, bool: True if basic information is included in exception reports.
    
    Data, bool: True if partial application data is included in exception reports.
    
    FullData, bool: True if partial application data is included in exception reports.
    
    Expiration, tuple: Specifies whether application data is included in expiration reports.
    
    Basic, bool: True if basic information is included in expiration reports.
    
    Data, bool: True if partial application data is included in expiration reports.
    
    FullData, bool: True if partial application data is included in expiration reports.
    
    COA, tuple: Specifies whether application data is included in confirmation on arrival reports.
    
    Basic, bool: True if basic information is included in COA reports.
    
    Data, bool: True if partial application data is included in COA reports.
    
    FullData, bool: True if partial application data is included in COA reports.
    
    COD, tuple: Specifies whether application data is included in confirmation on delivery reports.
    
    Basic, bool: True if basic information is included in COD reports.
    
    Data, bool: True if partial application data is included in COD reports.
    
    FullData, bool: True if partial application data is included in COD reports.
    
    NewMsgId, bool: True to use a new message ID in the report or reply.
    
    PassMsgId, bool: True to use the ID from original message in the report or reply.
    
    CopyMsgIdToCorrelId, bool: True to use the ID of the original message ID for the correlation ID in the report or reply.
    
    PassCorrelId, bool: True to use specified correlation in the report or reply.
    
    DealLetterQ, bool: Dispose undelivered messages in the dead letter queue.
    
    DiscardMsg, bool: True to discard undelivered messages.
    
    PassDiscardAndExpiry, bool: True to pass on discarded and expired messages.
  - UserId, string: Identifies the user that originated the message. This field may be present only when the Set Identity Context property is enabled.
Output Port 1, OutputStatus: This output port emits status, information, and error tuples. The OutputStatus port has the following schema:
- type, string: Contains one of the following values describing the type of event that occurred:
  - Connection - A connection to the MQ server has gone up or down.
  - User Input - An input tuple used to send an MQ message was rejected.
  - Suspend/Resume - The adapter has been suspended or resumed.
  - Message - The adapter enqueued a message to the MQ queue.
- object, string: The name of the object related to the event:
  - Connection - The configured IBM WebSphere MQ server, including the host name, port number, the queue manager name, queue name, and channel name.
  - User Input - The contents of the rejected input tuple.
  - Suspend/Resume - The adapter's name on the canvas.
  - Message - The tuple used to generated the message that was enqueued to the MQ queue.
- action, string: The action associated with the event
  - Connection - Up or Down
  - User Input - Rejected or Accepted With Warning
  - Suspend/Resume - Suspending or Resumed
  - Message - Published
- message, string: A human-readable description of the event
- userInput, tuple: A copy of the tuple processed by the adapter when type type is User Input or null otherwise

Add an instance of the adapter to a new StreamBase application as follows:

In StreamBase Studio, create a project an EventFlow diagram to host the adapter.
Drag an instance of the IBM WebSphere MQ output adapter from the Operators and Adapter drawer in the Palette view to the canvas.
Select or double-click the adapter icon. In the Properties view, select the Adapter Properties tab and fill in values for the IBM WebSphere MQ server host, port, queue manager name, queue name, and channel name.
Connect Input and Output streams to the adapter input and output ports.
If send MQ messages verbatim, add a string field to the input stream connected to the adapter's input port. If generating XML messages, add or more tuple fields with the name(s) of the top-level XML elements to the input stream.

Typechecking and Error Handling

The IBM WebSphere MQ Output adapter generates the following typecheck messages to help you configure the adapter in your StreamBase application:

An invalid port number is provided.
The queue manager name is missing.
The queue name is missing.
The channel name is missing.
A non-string or -tuple field is present in the stream feeding the adapter's input port.
Two or more string fields are present in the stream feeding the adapter's input port.
The adapter is not configured to generate XML, but two or more top-level tuples fields are present in the stream feeding its input port.
The adapter is configured to generate XML, but no top-level tuples fields are present in the stream feeding its input port.
The reconnection interval is invalid (not between 1 and 60 seconds, inclusive).

The adapter emits tuples on the status port during runtime under various conditions:

A connection to the IBM WebSphere MQ server goes up or down.
An input tuple used to publish an MQ message is rejected.
The adapter is suspended or resumed.

Suspend and Resume Behavior

When suspended, the IBM WebSphere output adapter stops processing input tuples.

When resumed, the adapter begins processing input tuples again.