Post on 14-Sep-2019
transcript
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.