Operator XMSSource

Specialized toolkits - release 4.3.1.0-prod20190605 > com.ibm.streamsx.messaging 5.4.1 > com.ibm.streamsx.messaging.xms > XMSSource

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streamsx.messaging/op$com.ibm.streamsx.messaging.xms$XMSSource.svg

The XMSSource operator reads data from a WebSphere MQ queue or topic and creates tuples out of it.

Each input WebSphere MQ message is converted to a separate tuple and sent to the output stream. A single message cannot contain multiple tuples.

Behavior in a consistent region

The XMSSource operator cannot participate in a consistent region.

Exceptions

The following list describes the common types of exceptions that can occur:
  • Run time errors that halt the operator execution.
    • The XMSSource operator throws an exception and terminates in the following cases:
      • During the initial connect attempt, the reconnectionPolicy is set to NoRetry and the operator does not have a successful connection, or during transient connection failures the reconnectionPolicy is set to BoundedRetry and the operator does not have a successful connection after the number of attempts that are specified in the reconnectionBound parameter. Successive data is lost.
      • The queue name is unknown.
      • The user is not an authorized user of the queue.
      • The queue manager name is unknown.
      • The operator is unable to connect to the host.
      • The operator is unable to connect to the port.
  • Run time errors that cause a message to be dropped and an error message to be logged.
    • The XMSSource operator throws an exception and discards the message in the following cases:
      • A MapMessage does not contain the attributes that are specified in the native schema.
      • A MapMessage contains attributes whose data type does not match the data type that is specified in the native schema and the conversion fails.
      • A StreamMessage does not contain the attributes that are specified in the native schema.
      • A StreamMessage contains attributes whose data type does not match the data type that is specified in the native schema and the conversion fails.
      • A BytesMessage does not contain the attributes that are specified in the native schema.
      • The operator encounters a message that does not match the message class that is specified in the native schema.
      • When a negative length (-2, -4, or -8) is specified in the native schema for bytes and string data types and the message class is bytes, the operator expects that the XMS message starts with a 2, 4, or 8-byte length field. If there are insufficient bytes remaining in the XMS message, the operator discards the entire message and logs a run time error.
      • When a non-negative length is specified in the native schema for bytes and string, the operator attempts to read exactly that number of bytes from the BytesMessage. If there are insufficient bytes remaining in the XMS message, the operator discards the entire message and logs a run time error.
    • The discarded message is not sent to the WebSphere MQ queue or topic.
  • Compile time errors
    • The XMSSource operator throws a compile-time error in the following cases:
      • The message type is empty and a native schema is specified.
      • The message type is bytes, stream, or map and a native schema attribute name or type does not match the name or type of the attribute in the output stream schema.
      • An attribute appears twice in the native schema.
      • An attribute of type string or bytes appears in the native schema without a length parameter.
      • The connections.xml file does not conform to connections.xsd.
      • The connectionsDocument parameter refers to a nonexistent connections file.
      • The connectionsDocument parameter is not specified and there is no connections.xml file inside the etc directory.
      • An invalid value is specified for the message class.
      • The access parameter does not refer to an existing access element in the native schema.
      • The connection parameter does not refer to an existing access element in the native schema.

In all of these cases, the operator logs the exception in the console logs, as well as on the error output port, if applicable.

Note:
  • If the WebSphere MQ server goes down while the XMSSource operator is running and the reconnectionPolicy parameter is set to BoundedRetry or InfiniteRetry, the operator does not try to reconnect to WebSphere MQ. This problem occurs in XMSClient version 2.0.1 or lower
Examples

Summary

Ports
This operator has 0 input ports and 2 output ports.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 7 parameters.

Required: access, connection

Optional: connectionDocument, initDelay, period, reconnectionBound, reconnectionPolicy

Metrics
This operator reports 3 metrics.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Output Ports

Ports (0)

The XMSSource operator has one mandatory output port.

If only the mandatory output port is specified, the operator submits a tuple for each message that is successfully read from WebSphere MQ. The mandatory output port is mutating and its punctuation mode is Free.

Assignments
This port set allows any SPL expression of the correct type to be assigned to output attributes.

Properties

Ports (1)
The XMSSource operator has one optional output port. If both optional and mandatory output ports are specified, the operator:
  • Submits a tuple to the mandatory port for each message that is successfully read, and
  • Submits an error message to the optional output port if an error occurs.

The optional output port is mutating and its punctuation mode is Free. Only one tuple is sent per failed tuple. The optional output port contains one attribute of type rstring, which contains the error message.

Assignments
This port set requires that assignments made to output attributes must evaluate at compile-time to a constant.

Properties

Parameters

Required: access, connection

Optional: connectionDocument, initDelay, period, reconnectionBound, reconnectionPolicy

access

This mandatory parameter identifies the access specification name.

Properties

connection

This mandatory parameter identifies the name of the connection specification that contains an XMS element.

Properties

connectionDocument

This optional parameter specifies the path name of the file that contains the connection and access specifications, which are identified by the connection and access parameters. If the parameter is specified, it must have exactly one value that is a string constant. If the parameter is not specified, the operator uses the file that is in the default location ../etc/connections.xml. If a relative path is specified, the path is relative to the root of the application directory.

Properties

initDelay

This optional parameter specifies the number of seconds that the XMSSource operator delays before it starts to produce tuples. During the delay, the operator is blocked.

Properties

period

This optional parameter specifies the time period in seconds the operator waits before it tries to reconnect. You can use this parameter only when the reconnectionPolicy parameter is specified, otherwise a compile time error occurs. The default value for the period parameter is 60.

Properties

reconnectionBound

This optional parameter specifies the number of successive connections that are attempted for an operator. You can use this parameter only when the reconnectionPolicy parameter is specified and set to BoundedRetry, otherwise a compile time error occurs. If the reconnectionBound parameter is specified and the reconnectionPolicy parameter is not set, a compile time error occurs. The default value for the reconnectionBound parameter is 5.

Properties

reconnectionPolicy

This is an optional parameter that specifies the reconnection policy. The valid values are NoRetry, InfiniteRetry, and BoundedRetry. If the parameter is not specified, the reconnection policy is set to BoundedRetry with a reconnectionBound of 5 and a period of 60 seconds.

Properties

Code Templates

XMSSource

stream<${streamType}> ${streamName} = XMSSource()   {
	      param
            	connection : "${ConnectionSpecificationName}";
                access : "${AccessSpecificationName}";
          }

Metrics

nConnectionAttempts - Counter

The number of connection attempts that are made before a successful connection.

nMessagesDropped - Counter

The number of messages dropped.

nMessagesRead - Counter

The number of messages read successfully.

Libraries

IBM Message Service Client for C/C++ (XMS) libraries
Command
Library Name: gxi01l, gxi
Library Path: @XMS_HOME@/lib64
Include Path: @XMS_HOME@/tools/cpp/include, @XMS_HOME@/tools/c/include
WebSphere MQ Client libraries
Command
Library Path: @MQ_HOME@/lib64
Include Path: @MQ_HOME@/lib64
Code that is common to both XMSSource and XMSSink is located in a directory ../Common relative to both of these operators.
Command
Library Path: ../Common
Include Path: ../Common