MQ Toys

Version 1 modification 1 release 3

User Guide

Cezary Opacki

2

Overview .......................................................................................................................................................................... 3

ReadRFH2 Java Transformation Description ............................................................................................................ 6

SendRFH2Reply Java Transformation Description. ................................................................................................. 7

SendRFH2Request Java Transformation Description. ............................................................................................ 8

Installation procedure of sample workflows. .............................................................................................................. 9

Websphere MQ Setup ............................................................................................................................................. 10

Queue Source Setup ............................................................................................................................................... 11

Mapping Setup .......................................................................................................................................................... 12

Integration Service Setup ........................................................................................................................................ 12

3

Overview

Websphere MQ infrastructure can constitute a service bus. Informatica Power Center can

be used to develop MQ service provider and MQ service consumer. To achieve that,

PowerExchange for Websphere MQ and the MQ Toys java transformations are necessary.

Cases, when the MQ Toys are required is discussed in the following paragraphs.

PowerExchange for Websphere MQ connector is able to read messages from queue. The

MQ Source Qualifier is presented below:

It returns message descriptor fields and one binary port named MESSAGE_DATA, which

returns user data of received message. MESSAGE_DATA, as it is binary port type, cannot be

processed in the mapping with any out of the box transformation except for java transformation.

The ReadRFH2 java transformation is able to convert MESSAGE_DATA port from binary data

type to data types usable in a mapping. ReadRFH2 transformation presumes MESSAGE_DATA

to be in RFH2 format. JMS message format is a special case of RFH2 message format.

Power Exchange for Websphere MQ connector requires to use queues which are defined in

Workflow Manager connections option. Therefore. it does not allow to send message to randomly

generated queue and queue manager. This is the case when sending reply to dynamic queue.

The dynamic queue names are generated randomly by Websphere MQ. SendRFH2Reply java

transformation allows to send reply to randomly generated queue and queue manager.

Power Exchange for Websphere MQ connector does not allow to send message to queue

4

manager other then connection queue manager. In the paper it is referred as remote queue

manager. Both, SendRFH2Request and SendRFH2Reply can send message to local or remote

queue manager.

“MQToys” is set of java transformations which allow developing “MQ Series” integration as

shown in the following mappings.

The mapping reads requests from the “PowerExchange MQ” connector. The “ReadRFH2”

Java transformation converts binary message data in “RFH2 format” (JMS compliant) into a format

usable in the mapping. The “SendRFH2Reply” transformation sends a reply to requests using the

“RFH2 message structure. The reply is compliant with JMS. Additionally, this transformation allows

setting the JMS “usr” property, which is included in the “RFH2 Header”. The “STATUS” port

returns an “MQ Reason Code” of the “send” operation. The reply queue and reply queue manager

names are taken from the message descriptor of the request message. The message descriptor

fields are returned by the “PowerExchange MQ” source.

The following example shows how to build a mapping which reads messages from a flat file

and sends a request to a service created in a previous mapping. After receiving a reply from the

service, it writes error messages to a flat file. A router transformation checks “MQ Reason Codes”

and requests containing errors are written to the “SentErrors” flat file. ReadRFH2Reply

transformation (It is renamed ReadRFH2 transformation) converts binary reply data format of

RFH2 message to useable in the mapping. String contained in RFH2 message at the end of the

5

RFH2 structure is written to file QueueContent. So SourceStrings flat file and QueueContent flat

file should be alike. In the file QueueContent, at the end of line is the name of session and

“workflow run id”.

The next example shows how to check whether replies are sent to the proper requester. To

achieve this the following workflow was created.

Both sessions, s_SendRequest1 and s_SendRequest2, are running SendRequest

mappings. Both sessions send request with a string followed by session name. Request is

6

processed by wf_ReadFromQueue workflow and reply is sent back to proper session. Replies are

written to the files queuecontent1.out and queuecontent2.out. Session s_SendRequest1 writes to

queuecontent1.out and session s_SendRequest2 writes to queuecontent2.out. A correct session

name should be written in each file.

ReadRFH2 Java Transformation Description

Converts RFH2 message header from byte array to Power Center convenient format.

“RFH2” is a structure of message data used by “JMS”. “RFH2” allows for more functionality, as

“JMS” is a special variant of “RFH2”. To preserve code page and number encoding conversion

from MQ message code page to Integration Service code page additional input ports are required.

The values for MDencoding and MDcharacterSet must be equal to values for encoding and

characterSet from message descriptor. The message descriptor is returned by PowerExchange for

Websphere MQ connector.

Port name I/O Port description

InputBuffer Input MQ message data as binary buffer.

MDencoding Input Message Descriptor – encoding

MDcharacterSet Input Message Descriptor – characterSet

MDformat Input Message Descriptor – format

DVersion Input Message Descriptor – Version

MDmessageType Input Message Descriptor – messageType

MDexpiry Input Message Descriptor – expiry

MDreplyToQueueName Input Message Descriptor - ReplyToQueueName

MDreplyToQueueManagerName Input Message Descriptor - replyToQueueManagerName

MDpriority Input Message Descriptor – priority

MDcorrelationId Input Message Descriptor – correlationId

MDMsgId Input Message Descriptor – MsgId

STRUCID Output RFH2 header structure id.

VERSION Output RFH2 Structure version.

STRUCLENGTH Output RFH2 structure length.

ENCODING Output RFH2 encoding

CODECHARSETID Output RFH2 code page ID

FORMAT Output RFH2 format

7

FLAGS Output FLAGS field returned from RFH2 header.

NAMEVALUECCSID Output NAMEVALUECCSID field returned from RFH2 header.

MCDProp Output MCD property returned from RFH2 header.

JMSProp Output JMS property returned from RFH2 header.

USRProp Output USR property returned from RFH2 header.

MSGBODY Output Message body returned from RFH2 structure.

MQSERVER Output MQSERVER environment variable value set for integration service.

SendRFH2Reply Java Transformation Description.

This java transformation sends an “RFH2” reply to an “RFH2” message request. The

messages are compliant with JMS, but can be received by any application which can read

message data in “RFH2” format. The reply message is sent as a temporary message. “Correlation

ID” is set to the “Message ID” of the request message. All parameters including: “connection

queue manager”, “reply queue”, “reply queue manager” are calculated dynamically in the mapping.

Thus, replies to temporary, dynamic queues are possible.

Port name I/O Port description

CORRELID Input CorrelId, which is set in message descriptor of reply message. Set the port to message id of the request message.

QMGR_CONN Input Connection message queue manager name.

QMGR_CONN_HOSTNAME Input Connection queue manager host.

QMGR_CONN_PORT Input Port for connection queue manager.

QMGR_CONN_CHANNEL Input Connection channel name.

QMGR_DEST Input Queue manager name, to which reply message is sent.

QNAME_DEST Input Queue name, to which message is sent.

EXPIRY Input Expiration time for the message.

JMSUSRProp Input JMS USR property value, which is sent in RFH2 header.

MSGBODY Input RFH2 message body.

STATUS Output Returns MQ reason code.

8

MSGBODYOUT Output Returns message body, which was sent as a reply.

SendRFH2Request Java Transformation Description.

This java transformation allows sending a request or datagram to remote a queue manager

queue. If “TypeOfMessage” ="REQUEST&REPLY" the temporary request is sent and the

transformation awaits a reply. Otherwise, a persistent datagram is sent and the transformation

does not await a reply.

Port name I/O Port description

QMGR_CONN Input Connection message queue manager name.

QMGR_CONN_HOSTNAME Input Connection queue manager host.

QMGR_CONN_PORT Input Port for connection queue manager.

QMGR_CONN_CHANNEL Input Connection channel name.

QMGR_DEST Input Queue manager name, to which reply message is sent.

QNAME_DEST Input Queue name to which message is sent.

9

EXPIRY Input Expiration time for the message.

JMSUSRProp Input JMS USR property value which is sent in RFH2 header.

MSGBODY Input RFH2 message body.

ReplyQMGR Input Queue manager alias name to which reply must be sent. If the name is null, ReplyQMGR field is set to QMGR_DEST + ".BUS".

TypeOfMessage Input 'REQUEST&REPLY' - request, not persistent, waiting for reply.

'FIRE&FORGET' - datagram, persistent, not waiting for reply.

ModelQueue Input Model queue based on which is created dynamic, temporary reply queue. Queue is create only for TypeOfMessage='REQUEST&REPLY'.

WaitInterval Input Wait interval for replay in milliseconds. Default 50000 milliseconds.

MDencoding Output Message Descriptor – encoding

MDcharacterSet Output Message Descriptor – characterSet

MDformat Output Message Descriptor – format

MDVersion Output Message Descriptor – Version

MDmessageType Output Message Descriptor – messageType

MDexpiry Output Message Descriptor – expiry

MDreplyToQueueName Output Message Descriptor – ReplyToQueueName

MDreplyToQueueManagerName Output Message Descriptor – replyToQueueManagerName

MDpriority Output Message Descriptor – priority

MDcorrelationId Output Message Descriptor – correlationId

MDMsgId Output Message Descriptor – MsgId

STATUS Output MQ reason code. Zero if transformation ended successfully.

RFH2ReplayBody Output Reply body of received RFH2 message. NULL if TypeOfMessage='FIRE&FORGET'.

Installation procedure of sample workflows.

The MQ Toys package consists of “java transformations” and sample workflows. The Java

Transformations are delivered in two files. Use the file which is related to Websphere MQ version

installed on Integration Service host.

10

For Websphere MQ 6.x use the file MQToys_v1m1r3_MQ6x.xml

For Websphere MQ 7.x use the file MQToys_v1m1r3_MQ7x.xml

Further in this paper, the proper file will be referred to as MQToys.xml

The workflows are examples of the application of the provided java transformations. The

workflows communicate through Websphere MQ. To show how to send a request to the remote

queue manager one needs to build two message queue managers, “MQMRequester” and

“MQMServer”. Workflow “wf_ReadFromQueue” connects to queue manager “MQMServer”.

Workfow “wf_SendRequest” connects to the queue manager “MQMRequester”.

“Wf_SendRequest” workflow sends a request to the queue “ServerQueue” located in the queue

manager “MQMServer”. Workflow “wf_ReadFromQueue” reads the request and sends replies to

the temporary queue created by “wf_SendRequest” in the queue manager “MQMRequester”.

Websphere MQ Setup

On Integration Service host install Websphere MQ.

1. Set the environment variable CLASSPATH to com.ibm.mqjms.jar and com.ibm.mq.jar. The

variable can be set in the session level setting Java Classpath attribute. The picture below,

shows a setting for Windows. For Unix as path separator must be used “:”. For Windows it

is “;”.

11

The example path for Windows is shown above in the “Java Classpath” attribute. The example

path for Unix is shown below:

/opt/mqm/java/lib/com.ibm.mqjms.jar:/opt/mqm/java/lib/com.ibm.mq.jar

2. Unzip file “MQToys_v1m1r3.zip”. Change the current directory to the directory where

MQToys_v1m1r3.zip was unzipped.

3. In Windows run script SetupMQToys.bat. In Unix run script SetupMQToys.sh

The above scripts create queue managers MQMRequester and MQMServer. The queue

managers are required for example workflows.

Queue Source Setup

1. Create the “Message Queue” source like presented on the picture:

2. In the session s_readFromQueue setup connection attribute for SQ_LocalSourceQueue to

value LocalQueue like shown below:

12

Mapping Setup

1. Copy flat file SourceStrings to the PowerCenter SrcFiles directory. The file is located in the

directory where MQToys.zip was unpacked.

2. Import MQToys.xml with samples using Repository Manager’s import function.

3. In the mapping SendRequest change the appropriate parameter for the message queue

manager, MQMRequester. No further action needs to be taken provided that the queue

managers are on the same host as the Integration Service used to run the example.

Otherwise:

a. In the SendRequest mapping change the Expression Transformation named

SetDestination. Set QMGR_CONN_HOSTNAME port to the host name where the

queue manager MQMRequester was created.

Integration Service Setup

1. In the Integration Service set environment variables to the following:

a. MQSERVER=SYSTEM.DEF.SVRCONN/TCP/<HostName>(1417)

b. MQCCSID=1208

where <HostName> is the host name in which MQMServer is created.

2. Set Integration Service DataMovementMode to Unicode.