In this section: |
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.
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.
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:
The WebSphere listener requires that you register the following files that are in [MQSeries]/java/lib/:
|
Platform/Notes |
JAR Files |
|---|---|
|
JAR (Client-side) | |
|
All platforms |
|
|
Depending on the service pack and the platform, also register: |
|
|
OS/390 and z/OS, also register |
|
|
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 (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.
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) |
Case-sensitive name of the queue manager. |
|
Request Queue (required) |
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 |
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 |
Name of the queue where Service Manager keeps requests that failed (due to the back-end data server not being available). |
|
Duration |
Maximum time that a document can remain in the retry pending queue. |
|
Retry |
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, incoming messages on the queue are filtered to reject messages without this correlation id. |
|
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) |
Number to connect to an MQ Server Queue Manager. The default port number is 1414. |
|
Host (MQ Client only) |
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 |
Causes Service Manager to set 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 |
Causes Service Manager to set 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. |
|
Report Queue |
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. |
|
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 |
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 |
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. |
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:
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.
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) |
Location to where your reply is delivered. The format of the destination is Queue@QueueManager. |
|
Manager (required) |
Name of the queue manager to which the server must connect. |
|
Set Reply Correlation Id |
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 |
Message priority. The value must be greater than or equal to zero; zero is the lowest priority. |
|
Request COD |
Request Confirmation of Delivery report message. Requires a Report Queue. |
|
Request COA |
Request Confirmation of Arrival report message. Requires a Report Queue. |
|
Report Queue |
Reply information for the outgoing document. Intended as a report destination. |
|
Host (MQ Client only) |
Host on which the MQ Server is located. |
|
Port (MQ Client only) |
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 |
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:
|
|
Persistence |
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 |
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 |
When true, user header values are included in the RFH2 header. False is the default value. |
|
User registers |
If set to true, user-level registers are included in the generated RFH2 header. By default, this property is set to false. |
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:
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/ResourceEx ception |
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. |
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 |
|
|
Dependeng 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.
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 |
|
|
Queue Manager |
WebSphere MQ queue manager name. |
|
Channel |
Server connection channel name, only required for MQ client connection. |
|
Host |
Host name or IP address, required for MQ client connection only. |
|
Port |
Port number, required for MQ client connection only. |
|
Form of Acknowledgment |
The way the listener acknowledges received messages:
|
|
Receiver Name (required) |
Name of the queue on which input documents will be received for processing by Service Manager. |
|
Default Reply |
Default queue or topic to which response documents are written. |
|
Pending Queue |
Queue to hold documents pending retry. |
|
User |
User ID defined to the JMS Server. |
|
Password |
Valid password defined to the JMS Server. |
|
Duration |
Maximum time that a document can remain in the retry pending queue. |
|
Retry |
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 |
Maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests. |
|
Polling Interval |
Interval (in seconds) at which to check for new input or stop listener requests. 2.0 is the default value. |
|
Default Java File Encoding |
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 true, the default reply definition is used in addition to defined destinations. |
|
Error documents treated normally |
If true, error documents are processed by configured preemitters. |
|
Listener is Transaction Manager |
If true, agents run in a local transaction. Agents can roll back uncompleted transactions. |
|
Record in Activity Log(s) |
If set, activity on this channel will be recorded in the activity logs, else the activity will not be recorded. |
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:
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.
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) |
Queue address queue@queue_manager. |
|
Form of Output |
|
|
Queue Manager |
Websphere MQ queue manager name. |
|
Channel |
Server connection channel name. Required for MQ client connection only. |
|
Host |
Host name or IP address. Required for MQ client connection only. |
|
Port |
Port number. Required for MQ client connection only. |
|
Message Priority |
Outgoing message priority. If omitted, uses incoming message priority. |
|
User |
Valid user ID at broker. |
|
Password |
Valid password at the broker machine. |
|
Output Message Type |
Select Bytes, Text, or Dynamic. |
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 |