WebSphere MQ and MQJMS

In this section:

Reference:

The IBM WebSphere (formerly MQSeries) messaging products enable application integration by helping business applications to exchange information across different platforms by sending and receiving data as messages.

WebSphere consists of Native MQ and MQSeries JMS (MQJMS). These products handle network interfaces, assure once-only delivery of messages, deal with communication protocols, dynamically distribute workloads across available resources, handle recovery after system problems occur, and help make programs portable.

These actions are performed so that programmers can use their skills to handle key business requirements, instead of wrestling with underlying network complexities.

Note: Throughout this topic, the Native MQ listener is also referred to as WebSphere, MQSeries, or MQ.


Top of page

x
Queuing Messages With WebSphere MQ

Using the iWay Adapter for WebSphere, Service Manager can read messages arriving on a named queue and route the responses to either another queue or to a non-MQ destination. Similarly, messages received through any of the other Service Manager listeners can be directed to an MQ queue. During the message flow, Service Manager can apply the standard document analysis, validation, transformation, and business logic capabilities to the message. An optional pending facility ensures that messages are retried if appropriate resources are not available at the time of execution.

Service Manager also supports queue operations using the WebSphere client, so that each user need not install the full IBM WebSphere Server product.


Top of page

x
MQSeries Classes for Java Message Service (JMS)

MQSeries classes for Java Message Service is a set of Java classes that implement the Sun Microsystem Java Message Service specification. A JMS application can use the classes to send MQSeries messages to either existing MQSeries or new JMS applications. An application can be configured to connect as an MQSeries client using TCP/IP or directly using the Java Native Interface (JNI). If the client-style connection is used, no additional MQSeries code is required on the client machine.

Use of the MQSeries classes for Java Message Service offers benefits associated with using an open standard to write MQSeries applications, such as the protection of investment both in skills and application code. In addition, the JMS classes provide some additional features not present in the MQSeries classes for Java. These extra features include:


Top of page

x
Registering MQ JAR and DLL Files

The WebSphere listener requires that you register the following files that are in [MQSeries]/java/lib/:

Platform/Notes

JAR Files

JAR (Client-side)

MQ Version 6

  • com.ibm.mq.jar
  • connector.jar

MQ Version 7

Note: When using MQ Version 7, version 7.0.1.3 and higher is required.

  • com.ibm.mq.jmqi.jar
  • com.ibm.mq.jar
  • com.ibm.mq.headers.jar
  • com.ibm.mq.commonservices.jar
  • connector.jar

DLL (Server-side)

Register the DLL directory (this is the directory where the name interface resides), for example,

[mqseries home]/java/lib -classpath libpath

For some platforms, you must explicitly add HOME/java/lib to the path. For example, for OS/390 you must issue the following command:

export LIBPATH=/mqm/java/lib:$LIBPATH

For instructions on registering JAR files, see Registering Library Files and Setting JVM Options.


Top of page

x
WebSphere MQ Listener Properties

The following table lists and describes the WebSphere MQ listener properties. For instructions on creating a listener, see How to Create a Listener.

Property Name

Property Description

Manager (required)

The case-sensitive name of the queue manager.

Request Queue (required)

The case-sensitive name of the queue where request documents are received. (Queues are named message repositories upon which messages accumulate until they are retrieved by programs that service those queues. Queues are managed by a queue manager.)

Default Reply Queue

The default queue where responses are directed unless specified otherwise (for example, in the message header or in the request document or listener setting).

This property can be ignored if an outlet is already configured for the channel that is being used.

Pending Queue

The name of the queue where Service Manager keeps requests that failed (due to the back-end data server not being available).

Duration

The maximum time that a document can remain in the retry pending queue.

Retry

The interval between retrying pending requests contained in a message.

Filter By Msg Id

Service Manager accepts messages with this message header value only.

Filter By Correlation Id

If set to a value, then incoming messages on the queue are filtered to reject messages without this correlation ID (the set value).

Filter By Group Id

Service Manager accepts messages with this message header value only.

Message Priority

JMS defines ten levels of message priority with values 0 through 9, where 0 is the lowest and 9 is the highest. Zero through four are considered normal settings and five through nine, expedited. The Message Priority field is the default priority value set in the JMS header.

Port (MQ Client only)

The number to connect to an MQ Server Queue Manager. The default port number is 1414.

Host (MQ Client only)

The host on which the MQ Server is located.

Channel (MQ Client only)

Case-sensitive name of the SRV_CONN channel that connects with the remote MQ Server queue manager. The default value is SYSTEM.DEF.SVRCONN.

SSL CipherSpec

Defines which Secure Sockets Layer (SSL) specification should be used by the listener. SSL can only be used in client mode.

CCSID

Specifies the coded character set number to use, overriding the machine configured CCSID. If omitted, the configured CCSID is used.

Ignore MQ Conversions

If set to false (default), the normal MQ conversions will be performed. If set to true, the MQ conversions will be bypassed.

COD

Service Manager accepts Confirmation of Delivery (COD) messages. A global document type definition, which enables processing of these messages when received from MQSeries, is also created. By default, this property is set to false.

COA

Service Manager accepts Confirmation of Arrival (COA) messages. A global document type definition, which enables processing of these messages when received from MQSeries, is also created. By default, this property is set to false.

Request COD

If set to true, iSM sets the report property of an outgoing MQSeries message to request that a Confirmation of Delivery (COD) is sent to the report queue. By default, this property is set to false.

Request COA

If set to true, iSM sets the report property of an outgoing MQSeries message to request that a Confirmation of Arrival (COA) is sent to the report queue. By default, this property is set to false.

Received Report Handling

Determines how to handle received reports on the input queue. Selecting tree shows a tree of the data with elements describing the report. Selecting data shows the data as the message contents.

Note: If the channel is XML, then the incoming report data must be XML.

Report Queue

The destination to which MQSeries must send requested CODs and COAs.

User Headers

If set to true (default), user header values are included in the RFH2 header.

User Registers

If set to true, user-level registers are included in the generated RFH2 header. By default, this property is set to false.

Accept Zero Length Messages?

If set to true, messages with a zero length payload will be processed, treating the value of the Empty Message Signal as the content of the message.

Empty Message Signal

A string to treat as the content of a zero length message, if such messages are accepted. If not supplied, the default value is "".

Whitespace Normalization

Specifies how the parser treats whitespace in element objects. Select preserve (default) to turn off all normalization as prescribed by the XML Specification. Select condense to remove extra whitespaces in pretty printed documents and for compatibility with earlier versions.

Accepts non-XML (flat) only

Select true if non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run. By default, this property is set to false.

Optimize Favoring

Use this option to customize listener performance. For smaller transactions, select performance (default). For large payloads that could monopolize the amount of memory used by iWay Service Manager, select memory.

Multithreading

Indicates the number of worker threads. (Equivalent to the number of requests that Service Manager can handle in parallel.) Setting this to a value of greater than 1 enables the listener to handle a second request while an earlier request is being processed. The total throughput of a system is affected by the number of threads operating. The default value is 1. The maximum value is 99.

Execution Time Limit

The maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.

Polling Interval

Indicates the frequency (in seconds) that the listener returns control to Service Manager to determine if a stop listener was requested. The listener is constantly connected to the queue to retrieve incoming messages. The default value is 2.0.

Default Java File Encoding

The default encoding if incoming message is not self-declaring (that is, XML). The default value is Cp1252.

Agent Precedence

Sets the order by which Service Manager selects agents. Service Manager selects the agent or agents to process the document by searching through the configuration dictionary. Usually, it looks for a document entry in the configuration and when a match is found, the agent specified in that document entry is selected. If a matching document entry is not found or no agent is specified, the engine looks in the input protocol configuration (listener). For the processing agent to be taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>.

Possible values are <document> overrides <listener> (default) and <listener> overrides <document>.

Always Reply to Listener Default

If set to true, the default reply definition is used in addition to defined replies. By default, this property is set to false.

Error Documents Treated Normally

If set to true, error documents will get processed by any configured preemitters. By default, this property is set to false.

Listener is Transaction Manager

If set to true, agents run in a local transaction. Agents can roll back uncompleted transactions. By default, this property is set to false.

Record in Activity Log(s)

If set to true (default), activity on this channel will be recorded in the activity logs. If set to false, the activity will not be recorded.

Note: The WebSphere MQ listener supports streaming. Streaming is used for large documents or documents for which the application needs to split the input into sections under the same transaction. For more information on streaming and configuring streaming preparsers, see the iWay Service Manager Component and Functional Language Reference Guide.



x
Reference: WebSphere MQ Listener Special Registers

The following table lists and describes the special registers (SREGs) available on the WebSphere MQ listener.

Name

Level

Type

Description

backoutcount

Document

String

The current backout count of the message

correlid

Document

String

The correlation ID, which can be base64(id)

destination

Document

String

The default destination for reply (from message)

expiry

Document

String

The expiry field of the MQMD.

format

Document

String

The format field of the MQMD.

iwayconfig

System

String

The current active configuration name.

iwayhome

System

String

The base at which the server is loaded.

iwayworkdir

System

String

The path to base of the current configuration.

mqcharacterset

Document

String

The character set field of the MQMD.

msgid

Document

String

The message ID, which can be base64(id).

msgsize

Document

Integer

The physical length of the message payload.

name

System

String

The assigned name of the master (listener).

outmsgid

Document

String

The message ID to apply when emitting, which can be base64(id).

persistence

Document

String

The persistence field of the MQMD.

priority

Document

String

The priority of this message.

protocol

System

String

The protocol on which message was received.

putapplicationname

Document

String

The Put application name field of the MQMD.

queuedepth

Document

String

The current depth of the queue at time of lookup to this register. If it cannot be read, -1 is returned.

replytoq

Document

String

The replyto queue field of the MQMD.

replytoqmgr

Document

String

The replyto queue manager field of the MQMD.

report

Document

String

The report field of the MQMD.

reporttype

Document

String

The report type. This can be coa, cod or other.

type

Document

String

The type of the message. It can be either report, reply, request, or datagram.

userid

Document

String

The user ID field of the MQMD.

tid

Document

String

Unique transaction ID.



x
Websphere MQ Listener Configuration Example

You are receiving documents on a WebSphere MQ queue, named default running under a Queue Manager named QM_iwxfoc using a channel named SYSTEM.DEF.SVRCONN. Specify the listener values as follows:


Top of page

x
Configuring a WebSphere MQ Emitter

Messages are sent to the destinations at the completion of a workflow. The state of the document determines which destination is used. The order in which the destinations are used cannot be predicted. Destinations cannot accept responses. These configurations also are used to send a message over a different protocol.

Note: Configuring a WebSphere MQ emitter is not required if the emitter protocol used in the outlet of the channel is the same as the listener protocol used in the inlet of the channel. For more information on inlets and outlets, see Defining an Inlet and Defining an Outlet.

To route an output document to a protocol other than that of the listener, configure an emitter. For example, an application may send input over a TCP listener but want to route the output to a WebSphere MQ queue.



x
Reference: WebSphere MQ Emitter Properties

The following table lists and describes the WebSphere MQ emitter properties. For instructions on creating an emitter, see How to Create an Emitter.

Property Name

Property Description

Destination (required)

The location to where your reply is delivered. The format of the destination is Queue@QueueManager.

Manager (required)

The name of the queue manager to which the server must connect.

Set Reply Correlation Id

The correlation ID on which to be filtered. The correlation ID is set in the MQSeries header. Unless a base64() function is used in the correlation ID, the search correlation ID is assumed to be a Unicode string correlation ID. This follows the current rules for correlation ID in the rest of the system.

Message Priority

The message priority. The value must be greater than or equal to zero; zero is the lowest priority.

Request COD

The Request Confirmation of Delivery report message. Requires a Report Queue.

Request COA

The Request Confirmation of Arrival report message. Requires a Report Queue.

Report Queue

The reply information for the outgoing document. Intended as a report destination.

Host (MQ Client only)

The host on which the MQ Server is located.

Port (MQ Client only)

The number to connect to an MQ Server queue manager.

Channel (MQ Client only)

Case-sensitive name of the channel that connects with the remote MQ Server queue manager. SYSTEM.DEF.SVRCONN is the default channel name for MQSeries.

SSL CipherSpec

Defines that Secure Sockets Layer (SSL) is to be used. This is configured for the channel by the IBM Websphere MQ Administrator. SSL can be used only in client mode.

CCSID

Specifies the coded character set number to use, overriding the machine configured CCSID. If omitted, the configured CCSID is used.

Message Format

The format name of the message data. This is the name that the sender of the message can use to indicate the nature of the data in the message to the receiver. Any characters that are in the queue manager character set can be specified for the name, but iWay Software recommends that the name be restricted to uppercase A through Z or numeric digits 0 through 9. String is the default value.

Message Type

Type of MQ message to be written. Select one of the following values from the drop-down list:

  • datagram (default)
  • request
  • response

Persistence

The values allowed are queue, persistent, and non-persistent. Queue is the default value, which means that it is persistent as the queue is defined.

Expiry

The time that the message remains available in the system awaiting pick up. It is an integer measured in 1/10 seconds. No expiration is the default value.

User Headers

If set to true, user header values are included in the RFH2 header. If set to false user header values are not included in the RFH2 header (this is the default setting).

User registers

If set to true, user-level registers are included in the generated RFH2 header. By default, this property is set to false.



x
WebSphere MQ Emitter Configuration Example

You want to emit documents to a WebSphere MQ queue, named default, running under a Queue Manager named QM_iwxfoc using a channel named SYSTEM.DEF.SVRCONN. Specify the emitter values as follows:


Top of page

x
WebSphere MQSeries Troubleshooting

The following table lists and describes errors that you may encounter when using an MQ listener.

Error

Reason

Solution

setupQM: error received 
java.lang.UnsatisfiedLink
Error: no mqjbnd02 in 
java.library.path: [line 
9]

The system path was not updated to include the directory containing mqjdbnd02.dll.

Use the Path Settings pane to register [MQJAVA]\lib in the Path field. The server must be stopped and restarted for this to take effect.

Failed MQ operation 
Completion Code 2, Reason 
2058: 

Queue manager name not valid or not known.

Verify that the case-sensitive queue manager defined actually exists. Use the MQSeries explorer (or the DISPLAY QL command) to verify that it is running.

Failed MQ operation 
Completion Code 2, Reason 
2085

The system was unable to find the queue(s) specified.

Either the queue was not defined or was incorrectly spelled. The MQSeries listener is case-sensitive. Verify that the queue name exists and is entered in the Configure MQ Listener section in the correct case.

Cannot load MQ Series. 
Probable classpath error.  
Java.lang.NoClassdeffound
Error: 
javax/resource/ResourceException

For a detailed explanation, see http://www-3.ibm.com/software/ ts/mqseries/library/ manual01/en_US/ aqm7aq01/aqm7aq.htm.

Use the Path Settings pane to add connector.jar to the class path.

MQSeries Listener fails 
to connect Completion 
Code 2, Reason 2059 on 
AIX

Queue manager not available.

If you are using MQSeries V5.2, you can add an extra stanza to mqs.ini which affects the part of shared memory MQSeries uses when connecting. The property is IPCCBaseAddress and is set on a per queue manager basis. By default, this property is set to the value 8, but iWay Software recommends setting this to the value 11. The following is an example of an altered QueueManager stanza in an mqs.ini file:

QueueManager:                          
Name=MQJavaTest                            
Prefix=/var/mqm                            
IPCCBaseAddress=12

Values permitted for this property are 4, 5, 8, 9, 10, 11, or 12. For more information, see the MQSeries V5.2 documentation.

Also, when using MQSeries 5.2 in conjunction with Service Manager on the AIX platform with WebSphere, you must export the LDR_CNTRL variable as follows.

export 
LDR_CNTRL=MAXDATA=0x300
00000

Similar issues can be found in IBM Defect 114907.



x
Registering MQJMS JAR and DLL Files

You must register the following files, which are in the installation_drive:\install_folder\ibm\WebSphere MQ\Java\Lib\ directory:

Platform/Notes

JAR Files

JAR (Client-side)

All

  • com.ibm.mq.jar
  • com.ibm.mqjms.jar
  • fscontext.jar
  • connector.jar
  • jms.jar
  • j2ee.jar

Depending on service pack and platform, also register

com.ibm.mq.iiop.jar

OS/390 and z/OS, also register

jta.jar

Specify the location of the property files directory you receive when you install the MQSeries java classes, such as mqji_en_US.properties.

DLL (Server-side)

Register the DLL directory (the directory where the name interface resides), for example,

[mqseries home]/java/lib

For some platforms, you must explicitly add MQSERIES HOME/java/lib to the path. For example, for OS/390 you must issue the following command:

export LIBPATH=/mqm/java/lib:$LIBPATH

For instructions on registering JAR files, see Registering Library Files and Setting JVM Options.



x
MQJMS Listener Properties

The following table lists and describes the MQJMS listener properties. For instructions on creating a listener, see How to Create a Listener.

Property Name

Property Description

Form of Input

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

Queue Manager

The WebSphere MQ queue manager name.

Channel

The server connection channel name, only required for MQ client connection.

Host

The host name or IP address, required for MQ client connection only.

Port

The port number, required for MQ client connection only.

Form of Acknowledgment

The way the listener acknowledges received messages:

  • auto acknowledge
  • client provides
  • duplicates permitted
  • transactional

Receiver Name (required)

The name of the queue on which input documents will be received for processing by Service Manager.

Default Reply

The default queue or topic to which response documents are written.

Pending Queue

The queue to hold documents pending retry.

User

A valid user ID defined to the JMS Server.

Password

A valid password defined to the JMS Server.

Duration

The maximum time that a document can remain in the retry pending queue.

Retry

The interval between retrying pending requests.

Message Selector

If used, input is filtered by this selector.

Message Priority

Outgoing message priority (if omitted, uses incoming priority).

Output Message Type

Select Bytes, Text, or Dynamic.

Accepts non-XML (flat) only

Select true if non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run.

Optimize Favoring

Use this option to customize listener performance. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory.

Multithreading

Indicates number of worker threads (documents or requests) that Service Manager can handle in parallel. Setting it greater than 1 enables the listener to handle a second request while an earlier request is being processed. Default: 1 Max value: 99

Execution Time Limit

The maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.

Polling Interval

The interval (in seconds) at which to check for new input or stop listener requests. The default value is 2.0.

Default Java File Encoding

The default encoding if incoming message is not self-declaring (that is, XML).

Agent Precedence

Sets the order by which Service Manager selects agents. Service Manager usually looks for a document entry in the configuration library and when a match is found, the agent specified in that document entry is selected. If no matching document entry is found or agent specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>.

<document> overrides <listener> is the default value.

Always reply to listener default

If set to true, the default reply definition is used in addition to defined destinations.

Error documents treated normally

If set to true, error documents are processed by configured preemitters.

Listener is Transaction Manager

If set to true, agents run in a local transaction. Agents can roll back uncompleted transactions.

Record in Activity Log(s)

If set to true, activity on this channel will be recorded in the activity logs, else the activity will not be recorded.



x
MQJMS Listener Configuration Example

You are receiving documents on an MQJMS queue, named default, running under a Queue Manager named QM_iwxfoc using a channel named SYSTEM.DEF.SVRCONN. Specify the listener values as follows:



x
Configuring an MQJMS Emitter

Messages are sent to the destinations at the completion of a workflow. The state of the document determines which destination is used. The order in which the destinations are used cannot be predicted. Destinations cannot accept responses. These configurations also are used to send a message over a different protocol.

Note: Configuring an MQJMS emitter is not required if the emitter protocol used in the outlet of the channel is the same as the listener protocol used in the inlet of the channel. For more information on inlets and outlets, see Defining an Inlet and Defining an Outlet.

To route an output document to a protocol other than that of the listener, configure an emitter. For example, an application may send input over a TCP listener but want to route the output to an MQJMS queue.



x
MQJMS Emitter Properties

The following table lists and describes the MQJMS emitter properties. For instructions on creating an emitter, see How to Create a Listener.

Property Name

Property Description

Destination (required)

The queue address queue@queue_manager.

Form of Output

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

Queue Manager

The Websphere MQ queue manager name.

Channel

The server connection channel name. Required for MQ client connection only.

Host

The host name or IP address. Required for MQ client connection only.

Port

The port number. Required for MQ client connection only.

Message Priority

The outgoing message priority. If omitted, uses incoming message priority.

User

A valid user ID at broker.

Password

A valid password at the broker machine.

Output Message Type

Select Bytes, Text, or Dynamic.



Example: Local MQJMS Emitter Configuration Example

You want to emit documents to an MQJMS queue running under a local Queue Manager named QM_iwxfoc. Specify the emitter values as follows:


iWay Software