PROJECT MEMO

DATE: 8 February 2008

AUTHOR:

Antonio Zenzola 335 1247339 antonio.zenzola@oracle.com Configuring ODI JMS Queue connection to access IBM MQ Series JMS provider

SUBJECT:

Objective In the following notes you will find details on how to configure Oracle Data Integrator to access IBM MQ Series JMS Provider, using JMS Queue technology. The steps required to achieve to goal are : - setting up JNDI environment - copying IBM MQ libraries into ODI drivers directory - setting up JMS Queue connection in Topology - setting up the ODI project and implementing the Model - implementing the enqueue interface - implementing the dequeue interface The usecase is very simple : connect to MQ server, reference an already configured queue on the IBM MQ server, enqueue messages coming from 1 column of a database table, dequeue the same messages from the previous queue to another database table. Environment - MQ Series server 5.3.1, running on z/Os - ODI 10.1.3.4 installed on Win32 machine - MQ Client 6.0.3 (downloaded from IBM site) - Oracle RDBMS 10.2.0.1 for master and work repositories

Setting up JNDI environment In order to succesfully connect to MQ Server, ODI requires to setup a JNDI context factory in which it will be able to lookup a reference to a QueueConnectionFactory object. All the JMS operations will be done through the QueueConnection created from the looked up factory. We will use the SUNs com.sun.jndi.fscontext.RefFSContextFactory in order to create a file-system based JNDI namespace that will be populated from IBM JMSAdmin client command line tool and then reused from ODI Topology. 1) download IBM MQ Client software where you can find JMSAdmin tool 2) configure the JMSAdmin.config file in C:\Program Files\IBM\WebSphere MQ\Java\bin folder : INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory PROVIDER_URL=file:/C:/JNDI-Directory

3) run in the command shell the JMSAdmin.bat and type the following commands : DEFINE QCF(JMSDEMOCF) + SYNCPOINTALLGETS(YES) + TRAN(client) + HOST(10.0.1.249) CHAN(SYSTEM.DEF.SVRCONN) PORT(1414) + QMGR(MQ02) Q(JMSDEMOQueue) QUEUE(RHI.ESITI.DISPOSIZIONI.INCORDINARIE)

DEFINE

To force MQSTR message format, add the following directive to the previous DEFINE command : TARGCLIENT(MQ)

The HOST, PORT, QMGR (queue manager) and QUEUE parameters should correspond to those of your case. 4) Quit from JMSAdmin (type end or ctrl-c) : the result should be the c:\JNDI-Directory\.bindings file where JNDI file-system context factory is implemented. There are 2 objects created in the filesystem JNDI namespace : JMSDEMOCF, is the QMQueueConnectionFactory, and JMSDEMOQueue for the Queue object that reference the right JMS Queue destination running inside the MQ Server.

Copying IBM MQ libraries into ODI drivers directory To install the IBM MQ libraries inside ODI, copy the following files from C:\Program Files\IBM\WebSphere MQ\Java\lib int the ODI drivers folder : 1) com.ibm.mq.jar 2) com.ibm.mq.pcf-x.y.z.jar (where x.y.z comes from the client version you have downloaded, I've used the 6.0.3) 3) com.ibm.mqjms.jar 4) connector.jar 5) dbhcore.jar 6) fscontext.jar 7) jms.jar 8) jndi.jar 9) jta.jar 10) providerutil.jar

Setting up JMS Queue connection in Topology Run ODI Topology manager and create a new dataserver under JMS Queue technology. The result should be :

The JNDI resource should be the QCF (QueueConnectionFactory) specified in the DEFINE directove in the JMSAdmin tool, i.e. JMSDEMOCF. Try the connection and you will get OK. Then create the physical schema and the logical in the context you want.

Setting up the ODI project and implementing the Model Go to Designer, create a sample project and import the following KMs : IKM SQL to JMS Append (for enqueueing operation) LKM JMS to SQL (for dequeueing operation)

Create a Model linked on the JMS Queue technology, specify the logical schema created in the previous step. Then create a datastore, referencing JMSDEMOQueue resource (the JMS MQ destination specified in the JMSAdmin DEFINE directive above).

You will consider the queue payload as a flat file, so you need to specify the following parameter in the Files tab :

For the demo purpose we need only 1 column, but we can define any structure, as complex as we want.

Implementing the enqueue interface Create the enqueue interface, specifying a different staging area that points to an RDBMS logica schema :

Drag and drop the database table source and the JMSDEMOQueue in the target, then map the column.

Check in the Flow that the IKM SQL to JMS Append correctly specified, overwrite only the CLIENTID KM option by typing a sample clientid :

Now you can execute the interface and see in the Operator that all is OK. At the end of the execution, You are able also to view the content of the JMSDEMOQueue, directly from the model, by right-clicking on the datastore and click view data. Specify a CLIENTID. The records you are viewing are the enqueued messages. When you exit, ODI will asks if it should purge the queue, by issuing the commit command, or if not.

Implementing the dequeue interface Create the dequeue interface, specifying a different staging area that points to an RDBMS logica schema. Drag and drop the database table target and the JMSDEMOQueue in the source, then map the column. Check in the Flow that the LKM JMS to SQL is correctly specified, overwrite only the CLIENTID KM option by typing a sample clientid. Run the interface and check that the JMSDEMOQueue is now empty because the interface consumed all the messages.