117282088-jms

8/12/2019 117282088-jms

1/102

User and Administrator Guide

Informatica PowerCenterConnectfor JMS(Version 7.1.1)

8/12/2019 117282088-jms

2/102

Informatica PowerCenterConnect for JMS User and Administrator Guide

Version 7.1.1August 2004

Copyright 2002-2004 Informatica Corporation.

All rights reserved. Printed in the USA.

This software and documentation contain proprietary information of Informatica Corporation, they are provided under a license agreementcontaining restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. No

part of this document may be reproduced or transmitted in any form, by any means (electronic, photocopying, recording or otherwise)

without prior consent of Informatica Corporation.

Use, duplication, or disclosure of the Software by the U.S. Government is subject to the restrictions set forth in the applicable software

license agreement as provided in DFARS 227.7202-1(a) and 227.7702-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable.

The information in this document is subject to change without notice. If you find any problems in the documentation, please report them tous in writing. Informatica Corporation does not warrant that this documentation is error free.

Informatica, PowerMart, PowerCenter, PowerCenter Connect, PowerConnect, and PowerChannel are trademarks or registered trademarks of

Informatica Corporation in the United States and in jurisdictions throughout the world. All other company and product names may be trade

names or trademarks of their respective owners.

Portions of this software are copyrighted by DataDirect Technologies, 1991-2000.

Informatica PowerCenter products contain ACE (TM) software copyrighted by Douglas C. Schmidt and his research group at WashingtonUniversity and University of California, Irvine, Copyright 1993-2002, all rights reserved.

DISCLAIMER:Informatica Corporation provides this documentation as is without warranty of any kind, either express or implied,

including, but not limited to, the implied warranties of non-infringement, merchantability, or use for a particular purpose. The informationprovided in this documentation may include technical inaccuracies or typographical errors. Informatica could make improvements and/or

changes in the products described in this documentation at any time without notice.

8/12/2019 117282088-jms

3/102

Table of Contents iii

Table of Contents

List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

New Features and Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xii

PowerCenter Connect for JMS 7.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

PowerCenter Connect for JMS 7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . .xii

PowerCenter Connect for JMS 7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . .xii

About Informatica Documentat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii i

About this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Document Convent ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Other Informatica Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Visiting Informatica Customer Portal . . . . . . . . . . . . . . . . . . . . . . . . . xviiVisiting the Informatica Webzine . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Visiting the Informatica Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Visiting the Informatica Developer Network . . . . . . . . . . . . . . . . . . . . xvii

Obtain ing Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Chapter 1: Understanding PowerCenter Connect for JMS . . . . . . . . .1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Integrating PowerCenter with JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Designer Integration with JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

JMS Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

PowerCenter Server and JMS Integration . . . . . . . . . . . . . . . . . . . . . . . .5

Chapter 2: Installation and Configuration . . . . . . . . . . . . . . . . . . . . . .7

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Minimum System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Setting Paths on UNIX and Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Step 1. Set Library Paths for the PowerCenter Server . . . . . . . . . . . . . . . .9

Step 2. Set the Path to the JVM Library File . . . . . . . . . . . . . . . . . . . . .10

Configuring JVM Options for the PowerCenter Server . . . . . . . . . . . . . . . . . 11

Configuring JVM Options for the PowerCenter Server on Windows . . . .11

8/12/2019 117282088-jms

4/102

iv Table of Contents

Configuring JVM Options for the PowerCenter Server on UNIX or

Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Registering JMS Provider Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . .14

Copying the JMS Provider Libraries to the PowerCenter Server

Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Setting the CLASSPATH to the JMS Provider Client Libraries in

Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Registering the JMS Provider Client Libraries in UNIX or Linux . . . . . . 14

Configuring Application Connection Properties . . . . . . . . . . . . . . . . . . . . . 15

Connection Attributes for JNDI Application Connections . . . . . . . . . . .15

Connection Attributes for JMS Application Connections . . . . . . . . . . . . 16Configuring JNDI and JMS Application Connections . . . . . . . . . . . . . . 17

Chapter 3: Working with JMS Sources and Targets . . . . . . . . . . . . .19

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Work ing wi th Header Fie lds in a JMS Target . . . . . . . . . . . . . . . . . . . . . 23

Maintaining Transactional Consistency for JMS Targets . . . . . . . . . . . . . 23Creating a JMS Source Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Creating a JMS Target Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Manually Creating a JMS Target Definition . . . . . . . . . . . . . . . . . . . . .25

Creating a JMS Target Definition Based on a JMS Source Definition . . .25

Editing JMS Source and Target Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 26

Working wi th the Application Source Qual if ier . . . . . . . . . . . . . . . . . . . . . . 30

Creating an Application Source Qualifier . . . . . . . . . . . . . . . . . . . . . . .30

Configuring an Application Source Qualifier . . . . . . . . . . . . . . . . . . . . . 30

Transform ation Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 4: Creating and Configuring JMS Workflows . . . . . . . . . . . . 33

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Loading JVM During a Session Run . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Reading and Writing JMS Messages in Sequence . . . . . . . . . . . . . . . . . . 34

Working wi th JMS Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Filtering Source Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Configuring Session Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Message Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Configuring JMS Header Fields in the Session Properties . . . . . . . . . . . . 41

Configuring Transactional Consistency for JMS Targets . . . . . . . . . . . . . 41

8/12/2019 117282088-jms

5/102

Table of Contents v

Pipeline Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Configuring Continuous Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Configuring a Session with a JMS Mapping . . . . . . . . . . . . . . . . . . . . . . . . 44

Scheduling Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Appendix A: JMS Datatype Reference . . . . . . . . . . . . . . . . . . . . . . . . 55

Datatype Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

JMS and Trans formation Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Boolean Datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Reading From JMS Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Appendix B: Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Using Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Appendix C: JMS Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

JMS Error Messages Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Designer Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Server Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

CMN Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

JMS Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

JSDK Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

TE Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

8/12/2019 117282088-jms

6/102

vi Table of Contents

8/12/2019 117282088-jms

7/102

List of Figures vii

List of Figures

Figure 1-1. PowerCente r and JMS Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Figure 1-2. PowerCente r Server and JMS Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Figure 2-1. JNDI Connection Object De finition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Figure 2-2. JMS Connection Object Def inition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Figure 3-1. Defaul t JMS Source and Target Def initions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Figure 3-2. Edit Tabl es Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Figure 3-3. JMS Source and Target Definiti ons in TextMessage Forma t . . . . . . . . . . . . . . . . . 22

Figure 3-4. Mapping with a JMS Source Definition and an Application Source Qualifier . . . . 30

Figure 4-1. Message Se lector in the Session Pr operties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figure 4-2. Session Conditions in the Ses sion Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Figure 4-3. Recovery Cache Folder in the Session Properties . . . . . . . . . . . . . . . . . . . . . . . . . 40

8/12/2019 117282088-jms

8/102

viii List of Figures

8/12/2019 117282088-jms

9/102

List of Tables ix

List of Tables

Table 1-1. JM S Message Header Fie lds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Table 2-1. System Env ironment Variable Path s on UNIX and Linux . . . . . . . . . . . . . . . . . . . . . 9Table 2-2. L ibrary Paths for JRE on UNIX and Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Table 2-3. JVM Library Names on UNIX and Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Table 2-4. JV M Library File Names on UNIX and Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Table 2-5. JNDI Application Conn ection Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Table 2-6. JM S Application Conne ction Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Table 3-1. Message Header Fields in JMS Source and Target Definitions . . . . . . . . . . . . . . . . 20

Table 3-2. JM S Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Table 4-1. Partition Typ es for Partition Points in JMS Mappings . . . . . . . . . . . . . . . . . . . . . . 42

Table A-1. JMS and Transformation Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Table A-2. Source Datatype s and Compatible JMS Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . 57

8/12/2019 117282088-jms

10/102

x List of Tables

8/12/2019 117282088-jms

11/102

xi

Preface

Welcome to PowerCenterConnect, Informaticas family of packaged software products thathelps you extract data and metadata from ERP and other third-party applications.

PowerCenterConnect for JMSis a natural extension to the open architecture ofPowerCenter, which supports data extraction from a wide variety of operational data sources.PowerCenter Connect for JMS allows you to directly extract data from JMS messages,transform the data according to your business rules, and load data into JMS messages or data

warehouses.

8/12/2019 117282088-jms

12/102

xii Preface

New Features and Enhancements

This section describes new features and enhancements to PowerCenter Connect for JMS 7.0,7.1, and 7.1.1.

PowerCenter Connect for JMS 7.1.1

PowerCenter Connect for JMS 7.1.1 has the following new features and enhancements:

! Support for SuSe Linux.You can now instal l PowerCenter Connect for JMS for thePowerCenter Server and Repository Server on SuSe Linux.

PowerCenter Connect for JMS 7.1

PowerCenter Connect for JMS 7.1 has the following new features and enhancements:

! 64-bit support.You can now run PowerCenter Connect for JMS on 64-bit AIX and HP-UX (Itanium).

! Support for Red Hat Linux.You can now install PowerCenter Connect for JMS for thePowerCenter Server and Repository Server on Red Hat Linux.

PowerCenter Connect for JMS 7.0

PowerCenter Connect for JMS 7.0 has the following new features and enhancements:

! Real-time processing enhancements.You can now use real-time processing in sessions thatalso process active transformations, such as the Aggregator transformation. You can apply

the transformation logic to rows defined by transaction boundaries.

8/12/2019 117282088-jms

13/102

Ab ou t Inf ormati ca Do cume ntat ion xi ii

About Informatica Documentation

The complete set of documentation for PowerCenter includes the following books:

!

Data Profiling Guide.Provides information about how to profile PowerCenter sources toevaluate source data and detect patterns and exceptions.

! Designer Guide.Provides information needed to use the Designer. Includes information tohelp you create mappings, mapplets, and transformations. Also includes a description ofthe transformation datatypes used to process and transform source data.

! Getting Started.Provides basic tutorials for getting started.

! Installation and Configuration Guide.Provides information needed to install and

configure the PowerCenter tools, including details on environment variables and databaseconnections.

! PowerCenterConnectfor JMSUser and Administrator Guide. Provides informationto install PowerCenter Connect for JMS, build mappings, extract data from JMS messages,and load data into JMS messages.

! Repository Guide. Provides information needed to administer the repository using theRepository Manager or thepmrep command line program. Includes details on

functionality available in the Repository Manager and Administration Console, such ascreating and maintaining repositories, folders, users, groups, and permissions andprivileges.

! Transformation Language Reference.Provides syntax descriptions and examples for eachtransformation function provided with PowerCenter.

! Transformation Guide.Provides information on how to create and configure each type oftransformation in the Designer.

! Troubleshooting Guide.Lists error messages that you might encounter while usingPowerCenter. Each error message includes one or more possible causes and actions thatyou can take to correct the condition.

! Web Services Provider Guide.Provides information you need to install and configure the WebServices Hub. This guide also provides information about how to use the web services that the

Web Services Hub hosts. The Web Services Hub hosts Real-time Web Services, Batch WebServices, and Metadata Web Services.

!

Workflow Administration Guide.Provides information to help you create and runworkflows in the Workflow Manager, as well as monitor workflows in the WorkflowMonitor. Also contains information on administering the PowerCenter Server andperformance tuning.

! XML User Guide.Provides information to create PowerCenter definitions from XML,XSD, or DTD file s, and relational or XML definitions. Includes information on runningsessions with XML data. Also includes details on using the Midstream XMLtransformation to extract or generate XML within a pipeline.

8/12/2019 117282088-jms

14/102

x iv Preface

Documentation available with our other products includes:

! InformaticaHIPAA Business Components User and Administrator Guide. Providesinformation on how to install and configure HIPAA Business Components to read andgenerate valid HIPAA transactions.

! InformaticaMetadata Exchange SDKUser Guide.Provides information about thesecond generation of Metadata Exchange interfaces for PowerCenter repositories.

! Metadata Exchange for Data Models User Guide.Provides information on how to extractmetadata from leading data modeling tools and import it into PowerCenter repositoriesthrough Informatica Metadata Exchange SDK.

! Metadata Exchange for OLAP User Guide.Provides information on how to use exportmulti-dimensional metadata from PowerCenter repositories into the Hyperion Integration

Server through Informatica Metadata Exchange SDK.

! Informatica PowerChannelUser Guide.Provides information on how to transportcompressed and encrypted data through a secure channel.

! PowerCenterConnect for IBMMQSeriesUser and Administrator Guide.Providesinformation to install PowerCenter Connect for IBM MQSeries, build mappings, extractdata from message queues, and load data to message queues.

! PowerCenterConnect for MSMQ User and Administrator Guide.Provides informationto install PowerCenter Connect for MSMQ, build mappings, extract data from messagequeues, and load data to message queues.

! PowerCenterConnectfor PeopleSoftUser and Administrator Guide.Providesinformation to insta ll PowerCenter Connect for PeopleSoft, extract data from PeopleSoftsystems, build mappings, and run workflows to load PeopleSoft source data into a

warehouse.

! PowerCenterConnect for SAP BWUser and Administrator Guide.Providesinformation to install and configure PowerCenter Connect for SAP BW to load sourcedata into an SAP Business Information Warehouse.

! PowerCenterConnect for SAP R/3Analytic Busine ss ComponentsGuide. Providesinformation on installing and working with Analytic Business Components forPowerCenter Connect for SAP R/3, including descriptions of repository objects and howyou can use them to load a data warehouse.

! PowerCenterConnect for SAP R/3User and Administrator Guide.Providesinformation to install PowerCenter Connect for SAP R/3, build mappings, and run

workflows to extract data from SAP R/3 and load data into SAP R/3.

! PowerCenterConnect for SiebelUser and Administrator Guide.Provides informationto install PowerCenter Connect for Siebel, extract data from Siebel systems, buildmappings, and run workflows to load Siebel source data into a data warehouse.

! PowerCenterConnect for TIBCOUser and Administrator Guide.Providesinformation to install PowerCenter Connect for TIBCO, build mappings, extract datafrom TIBCO messages, and load data into TIBCO messages.

8/12/2019 117282088-jms

15/102

Ab ou t Inf ormati ca Do cume ntat ion xv

PowerCenterConnect for webMethodsUser and Administrator Guide.Providesinformation to install PowerCenter Connect for webMethods, build mappings, extract datafrom webMethods documents, and load data into webMethods documents.

PowerCenterConnect for Web Services User and Administrator Guide.Provides

information to install PowerCenter Connect for Web Services, extract data from a webservice source, transform data using a web service, and load data into a web service target.

PowerCenterConnect Software Development Kit Developer Guide.Providesinformation to install PowerCenter Connect SDK and build plug-ins to extract data fromthird-party applications and load data into third-party applications.

8/12/2019 117282088-jms

16/102

xvi Preface

About this Book

The Informatica PowerCenter Connect for JMS User and Administrator Guideprovidesinformation to install PowerCenter Connect for JMS, build mappings, extract data from JMS

messages, and load data into JMS messages. It is written for the database administrators anddevelopers who are responsible for extracting data from JMS messages and loading data into

JMS messages.

This book assumes you have knowledge of relational database concepts and database engines,PowerCenter, JMS, and JNDI. You should also be familiar with the interface requirements forother supporting applications. For additional information about related JMS issues, refer toyour JMS documentation.

The material in this book is available in online help.

Document Conventions

This guide uses the following formatting conventions:

If you see It means

italicized text The word or set of words are especially emphasized.

boldfaced text Emphasized subjects.

italicized monospaced text This is the variable name for a value you enter as part of an

operating system command. This is generic text that should be

replaced with user-supplied values.

Note: The following paragraph provides additional facts.

Tip: The following paragraph provides suggested uses.

Warning: The following paragraph notes situations where you can overwriteor corrupt data, unless you follow the specified procedure.

monospaced text This is a code example.

bold monospaced text This is an operating system command you enter from a prompt to

run a task.

8/12/2019 117282088-jms

17/102

Other Informatica Resources xvii

Other Informatica Resources

In addition to the product manuals, Informatica provides these other resources:

!

Informatica Customer Portal! Informatica Webzine

! Informatica web site

! Informatica Developer Network

! Informatica Technical Support

Visiting Informatica Customer PortalAs an Informatica customer, you can access the Informatica Customer Portal site athttp://my.informatica.com. The site contains product information, user group information,newsletters, access to the Informatica customer support case management system (ATLAS),the Informatica Knowledgebase, Informatica Webzine, and access to the Informatica usercommunity.

Visiting the Informatica WebzineThe Informatica Documentation team delivers an online journal, the Informatica Webzine.This journal provides solutions to common tasks, detailed descriptions of specific features,and tips and tricks to help you develop data warehouses.

The Informatica Webzineis a password-protected site that you can access through theCustomer Portal. The Customer Portal has an online registration form for login accounts toits webzine and web support . To register for an account, go to http://my.informatica.com.

If you have any questions, please email [email protected].

Visiting the Informatica Web Site

You can access Informaticas corporate web site at http://www.informatica.com. The sitecontains information about Informatica, its background, upcoming events, and locating your

closest sales office. You will also find product information, as well a s literature and partnerinformation. The services area of the site includes important information on technicalsupport, training and education, and implementation services.

Visiting the Informatica Developer Network

The Informatica Developer Network is a web-based forum for third-party softwaredevelopers. You can access the Informatica Developer Network at the following URL:

http://devnet.informatica.com

8/12/2019 117282088-jms

18/102

xviii Preface

The site contains information on how to create, market, and support customer-oriented add-on solutions based on Informaticas interoperability interfaces.

Obtaining Technical Support

There are many ways to access Informatica technical support . You can call or email yournearest Technical Support Center listed below or you can use our WebSupport Service.

WebSupport requires a user name and password. You can request a user name and password athttp://my.informatica.com

North America / South America Africa / Asia / Australia / Europe

Informatica Corporation2100 Seaport Blvd.

Redwood City, CA 94063

Phone: 866.563.6332 or 650.385.5800

Fax: 650.213.9489

Hours: 6 a.m. - 6 p.m. (PST/PDT)

email: [email protected]

Informatica Software Ltd.6 Waltham Park

Waltham Road, White Waltham

Maidenhead, Berkshire

SL6 3TN

Phone: 44 870 606 1525

Fax: +44 1628 511 411

Hours: 9 a.m. - 5:30 p.m. (GMT)

email: [email protected]

BelgiumPhone: +32 15 281 702

Hours: 9 a.m. - 5:30 p.m. (local time)

France

Phone: +33 1 41 38 92 26


Germany

Phone: +49 1805 702 702Hours: 9 a.m. - 5:30 p.m. (local time)

Netherlands

Phone: +31 306 082 089


Singapore

Phone: +65 322 8589

Hours: 9 a.m. - 5 p.m. (local time)

Switzerland

Phone: +41 800 81 80 70

Hours: 8 a.m. - 5 p.m. (local time)

8/12/2019 117282088-jms

19/102

1

C h a p t e r 1

Understanding PowerCenter

Connect for JMS

This chapter covers the following topics:

Overview, 2

Integrating PowerCenter with JMS, 3

8/12/2019 117282088-jms

20/102

2 Chapter 1: Unders tand ing PowerCenter Connect for JMS

Overview

PowerCenter Connect for JMS integrates with JMS to extract data from JMS sources andwrite data to JMS targets . With PowerCenter Connect for JMS, you can define JMS sources

and targets in the Designer. You can use JMS source and target definitions in a mapping toread messages from JMS sources and write messages to JMS targets during a PowerCenter

workflow.

When extracting data from JMS or writing data to JMS, the PowerCenter Server connect s toa JMS provider. JMS providers are message-oriented middleware systems that can send andreceive JMS messages. IBM MQSeries JMS is an example of a JMS provider.

When the PowerCenter Server reads JMS messages from the source during a session, it can

read JMS messages from a JMS provider message queue. Or, it can read messages from a JMSprovider based on the message topic. When the PowerCenter Server writes JMS messages tothe target during a session, it can write JMS messages to a message queue. Or, it can writemessages to a JMS provider based on the message topic.

This chapter provides an overview of the integration between PowerCenter and JMS. Formore information about JMS, consult your JMS documentation.

8/12/2019 117282088-jms

21/102

Integrating PowerCenter with JMS 3

Integrating PowerCenter with JMS

PowerCenter Connect for JMS enables the PowerCenter Server to read messages from JMSsources and write messages to JMS targets. To read and write messages in JMS message

format, create mappings with JMS source and target definitions in the Designer. Once youcreate a mapping, use the Workflow Manager to create a session and workflow for themapping. When you run the workflow, the PowerCenter Server connects to JMS providers toread and write JMS messages.

Figure 1-1 shows the PowerCenter Server integration with JMS:

Designer Integration with JMSYou can manually create JMS source and target definitions in the Designer. JMS source andtarget definitions represent metadata for JMS messages. When you define a JMS source ortarget, you define the source or target to reflect the message structure of the JMS messagesyou want the PowerCenter Server to read or write according to the JMS message type.

JMS Message Types

The PowerCenter Server can read and write the following JMS message types:

Message.A Message does not contain message body fields . It contains only message headerand properties fields.

TextMessage.A TextMessage contains a Str ing object. JMS messages of this type cancontain XML message data.

BytesMessage.A BytesMessage is a stream of uninterpreted bytes. This message type is for

encoding a message body to match an existing message format. Messages of this typegenerally do not include property fields.

Figure 1-1. PowerCenter and JMS Integration

The Designer defines JMS source and target definitions for

use in JMS mappings.

The PowerCenter Server reads and writes JMS messages

during a PowerCenter workflow.

The Workflow Manager defines JMS sessions in workflows.

JMS providers act as sources from which the PowerCenter

Server can extract JMS messages. JMS providers also act as

targets to which the PowerCenter Server can write JMS

messages.

8/12/2019 117282088-jms

22/102


MapMessage.A MapMessage contains a set of name/value pairs. The names are in Stringformat. The values are Java primitive datatypes.

For more information about JMS message types, see Working with JMS Sources and Targetson page 19.

JMS Message Structure

JMS messages contain the following components:

Header

Properties

Body

Message Header Fields

JMS messages contain a fixed number of header fields. Each JMS message uses these fieldsregardless of message type. Every JMS source and target definition includes a pre-defined setof header fields. For more information about the header fields in JMS source and targetdefinitions, see Working with JMS Sources and Targets on page 19.

Table 1-1describes the JMS message header fields:

Table 1-1. JMS Message Header Fields

Header Field Description

JMSDestination The destination to which the message is sent. JMS destinations can be a message queue

or a recipient who listens for messages based on the message topic.

JMSDeliveryMode The delivery mode of the message. The delivery mode can be persistent or non-persistent.

JMSMessageID A unique identification value for the message.

JMSTimestamp The t ime a t wh ich the message was handed off to the provider to be sent to the

destination.

JMSCorrelationID Links one message with another. For example, JMSCorrelationID can link a response

message with the corresponding request message.

JMSReplyTo The destination to which a reply message can be sent.

JMSType The type of message based on a description of the message. For example, if a message

contains a stock trade, the message type may be stock trade.

JMSExpira tion The amount o f t ime in mil liseconds the message remains valid to be rece ived. The

messages remain in memory during this period.

JMSPr iori ty The pr ior ity of the message on a scale of 0-9. 0 i s the lowes t pr ior ity. 9 i s the highest .

JMSRedelivered Indicates that a message may have been delivered previously, but not acknowledged.

8/12/2019 117282088-jms

23/102

Integrating PowerCenter with JMS 5

Message Property Fields

JMS source and target definitions can inc lude JMS property fields. JMS property fields areoptional fields that contain additional message header information. JMS providers usemessage properties in a JMS message to give provider-specific information. Addit ionally,applications using a JMS provider can add property fields with application-specificinformation to a message.

Message Body Fields

JMS source and target definitions can inc lude a JMS message body. The message bodycontains one or more message body fields. The body is an optional component of a JMSmessage. Only certain types of JMS messages contain a message body.

PowerCenter Server and JMS Integration

During a workflow, the PowerCenter Server connects to the Java Naming and DirectoryInterface (JNDI) server to determine connection information for the JMS provider that is thesource or target for the JMS message data. Once the PowerCenter Server determines theconnection information, it connects to the JMS provider to read or write JMS messages.

The PowerCenter Server can read or write messages based on the message domain. It can readmessages from a JMS provider and write messages to a JMS provider according to the messagetopic. Or, it can read messages from a JMS provider queue and write messages to a JMSprovider queue.

Figure 1-2 shows how the PowerCenter Server connects to the JNDI server and JMS providersduring a session to read and write messages:

Figure 1-2. PowerCenter Server and JMS Integration

The PowerCenter Server reads and writes JMS

messages based on workflow and application

connection configurations.

The PowerCenter Server connects to JMS

providers to read and write JMS messages

according to the message domain.

The PowerCenter Server connects to the JNDIserver to retrieve connection information to

connect to a JMS p rovider.

C ti t JMS P id

8/12/2019 117282088-jms

24/102


Connecting to JMS Providers

When you configure a workflow to read messages from a JMS provider or write messages to aJMS provider, you use JNDI and JMS application connections to connect to the provider.

JMS providers use JNDI to store their connection information. When you configure a JMS

provider to send and receive messages, you configure JNDI information for the provider.JNDI stores the following connection information:

Connection factory. The connection factory contains information for creating aconnection to the JMS provider. For example, a connection factory for an MQSeries JMSprovider may contain information about a host name and port number for the provider.

Destination. The destination contains information about message sources anddestinations. For example, a destination for an MQSeries JMS provider may contain

information about a queue name and queue manager.In the Workflow Manager, you configure a JNDI application connection. In the JNDIapplication connection, you set connection information that enables the PowerCenter Serverto connect to the JNDI server.

You also configure a JMS appl icat ion connect ion in the Workflow Manager. In the JMSapplication connection, you provide a connection factory name and a destination name. Youalso provide a domain for the messages.

During the session, the PowerCenter Server connects to the JNDI server based on the JNDIconnection information you provide in the JNDI application connection. When it connectsto JNDI, it uses the connection factory name you provide in the JMS application connectionto retrieve the JMS provider connection information. It also uses the destination name youprovide to determine the source and target for JMS messages.

It then reads JMS messages from the source provider or writes JMS messages to the targetJMS provider according to the message domain you specified in the JMS application

connection.

Message Domains

The PowerCenter Server can read messages from JMS sources and write messages to JMStargets using either the point-to-point (PTP) or publish-subscribe domain.

The PTP domain means that JMS providers store messages in a message queue. When thePowerCenter Server reads messages using the PTP domain, it reads messages from the JMSprovider message queue. When the PowerCenter Server writes messages using the PTPdomain, it writes messages to a JMS provider message queue.

The publish-subscribe domain means that JMS providers read and write messages using themessage topic as the address. When the PowerCenter Server reads messages using the publish-subscribe domain, it receives messages with a part icular message topic from the JMS provider.

When the PowerCenter Server writes messages using the publish-subscribe domain, it writesmessages with a particular message topic to the JMS provider.

8/12/2019 117282088-jms

25/102

7

C h a p t e r 2

Installation and Configuration

This chapter includes the following topics:

! Overview, 8

! Setting Paths on UNIX and Linux, 9

! Configuring JVM Options for the PowerCenter Server, 11

! Registering JMS Provider Client Libraries, 14

! Configuring Application Connection Properties, 15

Overview

8/12/2019 117282088-jms

26/102

8 C ha pt er 2: In sta ll at ion an d C onf igu ra ti on

Overview

PowerCenter Connect for JMS installs automatically with the PowerCenter Server, Client,and Repository Server when you purchase the PowerCenter Real-time Option. To use

PowerCenter Connect for JMS, you must also install and configure a JMS provider, such asIBM MQSeries JMS or BEA WebLogic Server. The administrators of these systems shouldperform the installation and configuration tasks for their respective systems.

To install and configure PowerCenter Connect for JMS, complete the following steps:

1. Install the PowerCenter Server, Client, and Repository Server.You must install orupgrade to PowerCenter 7.1.1 with the PowerCenter Real-time Option. For moreinformation, see the PowerCenter Installation and Configuration Guide.

2. Set paths on UNIX or Linux. If you install the PowerCenter Server on UNIX or Linux,you must set library paths for the PowerCenter Server and set the path to the JVM libraryfile. For more information, see Setting Paths on UNIX and Linux on page 9.

3. Configure JVM parameters for the PowerCenter Server.For more information, seeConfiguring JVM Options for the PowerCenter Server on page 11.

4. Register JMS provider client libraries on the machine hosting the PowerCenter Server.

For more information, see Registering JMS Provider Client Libraries on page 14.5. Create and configure JMS application connection properties.The PowerCenter Server

uses JMS application connections to connect to a JMS provider when it reads messagesfrom a JMS source and writes messages to a JMS target. For more information, seeConfiguring Application Connection Properties on page 15.

Note: Read the release notes for any changes to installation or connectivity.

Minimum System RequirementsBefore installing and configuring PowerCenter Connect for JMS, complete the followingtasks:

! Install Java Runtime Environment (JRE). Install JRE on the machine hosting thePowerCenter Server. You can download JRE from http://java.sun.com/j2se .

! Install and configure a JMS provider.You can install the JMS provider on any machine.

However, you must also install the JMS provider client on the machine hosting thePowerCenter Server and register the JMS JAR files on the PowerCenter Server machine.For more information about your JMS provider, consult your JMS providerdocumentation. For more information about registering the JMS JAR files, seeRegistering JMS Provider Client Libraries on page 14.

Setting Paths on UNIX and Linux

8/12/2019 117282088-jms

27/102

Setting Paths on UNIX and Linux 9

Setting Paths on UNIX and Linux

If you installed the PowerCenter Server on UNIX or Linux, complete the following steps:

1. Set library paths for the PowerCenter Server.

2. Set the path to the JVM library file.

Step 1. Set Library Paths for the PowerCenter Server

If you installed the PowerCenter Server on UNIX or Linux, you must set library paths for JREin your Java directory.

Table 2-1describes the shared environment variables for which you set the library paths:

Follow these guidelines when you use a UNIX or Linux shell:

Set the library paths to the directories described in Table 2-2:

Table 2-1. System Environment Variable Paths on UNIX and Linux

Operat ing System Shared Library Envi ronment Var iable

AIX LIBPATH

HP-UX SHLIB_PATH

Solaris LD_LIBRARY_PATHLinux LD_LIBRARY_PATH

Shell To Modify Environment Variable

C shell setenv PATH : $PATH

Bourne shell PATH = ; export PATH

Table 2-2. Library Paths for JRE on UNIX and Linux

Operating System Library Path

AIX /jre/lib/jre/bin

/jre/classic

HP-UX /jre/lib/jre/lib/{PA_RISC|PA_RISC2.0}

/jre/lib/{PA_RISC|PA_RISC2.0}/{classic|hotspot}

/jre/lib/{PA_RISC|PA_RISC2.0}/native_threads

Enter PA_RISC or PA_RISC2.0 depending on the version of Jav a installed on your machine.

To determine the Java version, enter the following:

java -version

Table 2-2. Library Paths for JRE on UNIX and Linux

8/12/2019 117282088-jms

28/102

10 Chapter 2 : Ins ta ll at ion and Conf iguration

For example, to set the /jre/lib path to your Java home directory on AIX using the C shell,enter the following:

setenv LIBPATH Java/jre/lib:$LIBPATH

To set the /jre/lib path to your Java home directory on AIX using the Bourne shel l, enter thefollowing:

LIBPATH = Java/jre/lib; export LIBPATH

Step 2. Set the Path to the JVM Library File

Set the path to the JVM library file on UNIX or Linux using the C shell or Bourne shell.

Table 2-3describes the JVM library file names for each UNIX or Linux operating system:

Follow these guidelines when you use a UNIX or Linux shell:

For example, if the libjvm.sl library file is in the JVM/bin/hotspot directory on HP-UX, enterthe following path using the C shell:

setenv PATH JVM/bin/hotspot:$PATH

For example, if the libjvm.a library file is in the JVM/bin/classic directory on AIX, enter thefollowing path using the Bourne shell:

PATH = JVM/bin/hotspot; export PATH

Note: If the location of the JVM library file changes, you must set the path to the newlocation.

Solaris /jre/lib

Linux /jre/lib

Table 2-3. JVM Library Names on UNIX and Linux

Operating System JVM Library Name

AIX libjvm.a

HP-UX libjvm.sl

Solaris libjvm.so

Linux libjvm.so (JVM from Sun Microsystems)

UNIX/Linux Shell Description

C shell setenv PATH :$PATH

Bourne shell PATH = ; export PATH

Operating System Library Path

Configuring JVM Options for the PowerCenter Server

8/12/2019 117282088-jms

29/102

Configuring JVM Options for the PowerCenter Server 11

Configuring JVM Options for the PowerCenter Server

Once you install the PowerCenter Server, you must configure JVM options, including theJVM library file path and security parameters. Setting JVM options enables you to run Java-

based programs and establish security resources. For more information about configuring thePowerCenter Server, see the PowerCenter Installation and Configuration Guide.

Configuring JVM Options for the PowerCenter Server on Windows

Use the Informatica PowerCenter Server Setup to configure JVM options for the PowerCenterServer.

To configure JVM options for the PowerCenter Server on Windows:

1. If the configuration window does not display during the installation, choose InformaticaServer Setup from the Windows Start Menu.

2. Select the Configure Informatica Service option and click Continue.

3. Click the JVM Options tab.

4. Configure the following VM Options:

8/12/2019 117282088-jms

30/102


Note: The Advanced VM options do not apply to PowerCenter Connect for JMS.

5. Click OK to save the configuration options and close the Server Setup dialog box.

Configuring JVM Options for the PowerCenter Server on UNIX or

Linux

When you install PowerCenter Connect for JMS for the PowerCenter Server on UNIX or

Linux, use the pmconfig utility to configure JVM options for the PowerCenter Server. Theutility writes your configuration parameters to the pmserver.cfg file.

When you edit the pmserver.cfg file, you must specify the absolute path to the JVM libraryfile for the JVMDllPath configuration parameter.

Note:When you set the absolute path to the JVM library f ile, set the path to the samedirectory you specified when you set library paths for JRE in your Java directory.

Table 2-4describes the JVM library file names for each UNIX or Linux operating system:

VM OptionRequired/

OptionalDescription

VM L ocat ion R equired T he abs olute path t o the jvm .dll f ile. Info rmatica recommends that you

set the absolute path to the jvm.dll file in the Java \ hotspot directory forbest performance. When you change th e jvm.dll file location, you mustset the absolute path to the new location.

Classpath Optional You can set the CLASSPATH to any JAR files you need to run a session

using a JMS source, target, or transformation. The PowerCenter Server

appends the values you set to the system CLASSPATH.

MinMemory Optional Set this value to increase the minimum amount of memory for JVM to

use during a PowerCenter session. The default value is 32 MB.

If the session fails due to an out of memory error, you may want toincrease this value.

MaxMemory Optional Set this value to increase the maximum amount of m emory for JVM to


If the session fails due to an out of memory error, you may want toincrease this value.

Table 2-4. JVM Library File Names on UNIX and Linux

Operating System JVM Library Name

AIX lib jvm.a

HP-UX libjvm.sl

Solaris libjvm.so

Linux libjvm.so

To configure JVM options for the PowerCenter Server on UNIX or Linux:

8/12/2019 117282088-jms

31/102

Configuring JVM Options for the PowerCenter Server 13

1. Run the pmconfig utility and open pmserver.cfg.

Note: On Solaris, run ./pmconfig to avoid running the Solaris system command by thesame name. The PM_HOME environment variable must point to the PowerCenterdirectory.

2. Enter the following JVM options:

OptionRequired/

OptionalDescription

JVMD llPa th Required The absolute path t o the JVM library file. I nf ormatica recommends that

you enter the absolute path to the JVM library file in the Java /hotspotdirectory on HP-UX, Solaris, and Linux f or best performance.

When you change the JVM library file location, you must set theabsolute path to the new location.

JVMC las sP ath O ptional You can set the CLASS PATH to any JAR files you need to run a sess ion

using a JMS source, target, or transformation. The PowerCenter Server

appends the values you set to the system CLASSPATH.

JVMMinMemory Optional Set this va lue to i ncrease the min imum amount o f memory fo r JVM to


If the session fails due to a lack of memory, you may want to increase

this value.

JVMMaxMemory Optional Set this va lue to i ncrease the max imum amount o f memory fo r JVM to


If the session fails due to a lack of memory, you may want to increasethis value.

Registering JMS Provider Client Libraries

8/12/2019 117282088-jms

32/102


g g

To read JMS messages from JMS providers and write JMS messages to JMS providers, youmust register the JMS provider client libraries on the machine hosting the PowerCenter

Server. The JMS provider client libraries are JAR files that the JMS provider uses to run JMS.For more information about the client libraries your JMS provider uses, see your JMSprovider documentation.

To register the JMS provider librar ies, you can copy the libraries to the PowerCenter Serverdirectory, or you can set the CLASSPATH to the libraries.

Copying the JMS Provider Libraries to the PowerCenter Server

Directory

On Windows, UNIX, or Linux, you can copy the JMS provider libraries to the/bin/javalib directory. When you install the PowerCenter Server, theinstallation program creates this directory.

For example, if you want to register the MQSeries JMS client library com.ibm.mq.jar onWindows, you can copy the file to the following directory:

c:\Program Files\Informatica\PowerCenter Server\bin\javalib

Setting the CLASSPATH to the JMS Provider Client Libraries in

Windows

If the JMS provider client libraries are not in the JRE \ lib\ext directory, you must set theCLASSPATH to each JMS provider client library in Windows.

For example, to set the CLASSPATH to the MQSeries JMS client JAR file com.ibm.mq.jar,enter the following text:

;c:\Program Files\MQSeries\JMS\com.ibm.mq.jar

Registering the JMS Provider Client Libraries in UNIX or Linux

If the JMS provider client libraries are not in the JRE /lib/ext directory, you must set theCLASSPATH to each JMS provider client library.

For example, to set the CLASSPATH to the MQSeries JMS client JAR file com.ibm.mq.jarusing the C shell, enter the following text:

setenv CLASSPATH /home/MQSeries/JMS/com.ibm.mq.jar:$CLASSPATH

Configuring Application Connection Properties

8/12/2019 117282088-jms

33/102

Configuring Application Connection Properties 15

g g pp p

Before the PowerCenter Server can extract data from JMS sources or write data to JMStargets, you must configure application connections for JMS sources and targets in the

Workflow Manager. The PowerCenter Server uses application connect ions to connect to aJMS provide r during a session to read and write JMS messages. The application connect ionsyou define in the Workflow Manager are saved in the PowerCenter repository.

You must configure two types of JMS application connections:

! JNDI application connect ion

! JMS application connection

Connection Attributes for JNDI Application Connections

Configure a JNDI application connection to connect to a JNDI server during a workflow.When the PowerCenter Server connects to the JNDI server, it retr ieves information fromJNDI about the JMS provider that is the source or target for JMS messages during the session.When you configure a JNDI application connection, you must specify connect ion propertiesin the Connection Object Definition dialog box. For more information about PowerCenter

and JNDI integration, see Connecting to JMS Providers on page 6.Figure 2-1shows the Connection Object Definition dialog box for a JNDI applicationconnection:

Figure 2-1. JNDI Connection Object Definition

Table 2-5describes the attributes that you configure for a JNDI application connection:

8/12/2019 117282088-jms

34/102


For more information about JNDI, see your JMS documentation.

Connection Attributes for JMS Application Connections

Configure a JMS application connection to connect to JMS providers during a PowerCentersession to read source messages or write target messages. When you configure a JMSapplication connection, you specify connection properties the PowerCenter Server uses to

connect to JMS providers during a PowerCenter session. Specify the JMS applicationconnection properties in the Connection Object Definition dialog box.

Figure 2-2shows the Connection Object Definition dialog box for a JMS applicationconnection:

Table 2-5. JNDI Application Connection Attributes

Connection AttributesRequired/

OptionalDescription

JNDI Context Factory Required Enter the name of the context factory that you speci fied when you def ined

the context factory for your J MS provider.

JNDI Provider URL Requ ired Enter the p rov ider URL that you speci fi ed when you de fined the p rovider

URL for your JMS provider.

JNDI UserName Optional Enter a user name.

JNDI Password Optional Enter a password.

Figure 2-2. JMS Connection Object Definition

Table 2-6describes the attributes that you configure for a JMS application connection:

8/12/2019 117282088-jms

35/102

Configuring Application Connection Properties 17

For more information about JMS and JNDI, see your JMS documentation.

Configuring JNDI and JMS Application Connections

Use the following procedure to configure JNDI and JMS application connections.

To configure JNDI and JMS application connections:

1. In the Workflow Manager, connect to a PowerCenter repository.

2. Choose Connections-Application.

Table 2-6. JMS Application Connection Attributes

Connection AttributesRequired/

OptionalDescription

JMS Dest ination Type Required S elect QUEU E or TOPI C for t he JMS De stination Type. Select

QUEUE if you want to read source messages from a JMS provider

queue or write target messages to a JMS provider queue. Select

TOPIC if you want to read source messages based on the messagetopic or write target messages with a particular message topic.

JMS Connection Factory Name Required Enter the name of the connection factory. The name of the connection

factory must be the same as the connection factory name you

configured in JNDI. The PowerCenter Server uses the connection

factory to create a connection with the JMS provider.

JMS Destination Required Enter the name of the destination. The destination name must match

the name you configured in JNDI.

JMS UserName Optional Enter a user name.

JMS Password Optional Enter a password.

The Application Connection Browser dialog box appears.

8/12/2019 117282088-jms

36/102


3. From Select Type, select JNDI Connection or JMS Connection.

4.Click New.The Connection Object Definition dialog box appears.

5. Enter a name for the application connection.

6. Enter the values for the connection attributes.

7. Click OK.

The new application connection appears in the Application Connection Browser.

Tip: To edit or delete an application connection, select the connection from the list and clickthe appropriate button.

8/12/2019 117282088-jms

37/102

19

C h a p t e r 3

Working with JMS

Sources and Targets

This chapter covers the following topics:

Overview, 20

Creating a JMS Source Definition, 24

Creating a JMS Target Definition, 25

Editing JMS Source and Target Definitions, 26

Working with the Application Source Qualifier, 30

Overview

8/12/2019 117282088-jms

38/102

20 Chapter 3 : Work ing wi th JMS Sources and Targets

JMS source and target definitions represent metadata for JMS messages. When thePowerCenter Server extracts messages from a JMS source during a workflow, it reads messages

based on the message format defined in the source definition. When the PowerCenter Serverwrites messages to a JMS target during a workflow, it wri tes messages based on the formatdefined in the target definition.

You define JMS sources and targets in the Designer. When you define JMS sources andtargets, the Designer displays a table with message fields and JMS datatypes. When thePowerCenter Server extracts data from the JMS source, it converts the data based on thedatatypes in the Source Qualifier transformation associated with the source.

Every JMS source and target definition contains JMS message header fields. Sourcedefinitions contain the message header fields that are useful for reading messages from JMSsources. Target definitions contain the message header fields that are useful for writingmessages to JMS targets.

Table 3-1shows the message header fields JMS source and target definitions contain:

JMS source and target definit ions can also contain message property and body f ieldsdepending on which JMS message type the source or target definit ion represents. JMS sourceand target definitions can represent metadata for the following types of JMS messages.

Table 3-1. Message Header Fields in JMS Source and Target Definitions

JMS Message Header F ie ld JMS Source Defin it ion JMS Target Definit ion

JMSCorrelationID Yes Yes

JMSMessageID Yes No

JMSType Yes Yes

JMSDestination Yes Yes

JMSReplyTo Yes Yes

JMSDeliveryMode Yes Yes

JMSExpiration Yes No

JMSTimeToLive No Yes

JMSPriority Yes Yes

JMSTimestamp Yes No

JMSRedelivered Yes No

Table 3-2shows the types of JMS messages source or target definitions can represent:

Table 3-2 JMS Message Types

8/12/2019 117282088-jms

39/102

Overview 21

JMS sources and targets that you define repre sent messages of the type Message by default.Since JMS messages of the type Message do not contain body fields, default source and target

definitions do not contain body fields. The default source definition also does not containproperty fields. However, you can add property fields to the source definition since JMSmessages of the type Message can contain property fields.

Figure 3-1shows default JMS source and target definitions, which contain the default JMSheader fields and no property or body fields:

Once you create a JMS source or target definition, you can edit it to reflect changes in thesource or target data. For example, you can change the JMS message type. You can edit JMSmessage header, property, or body fields. You can change the datatype and precision ofmessage header, property, and body fields. You can also add and remove fields.

You edit message header fields from the JMS Message Header Columns tab of the Edit Tablesdialog box. You edit message property fields from the JMS Message Property Columns tab of

the Edit Tables dialog box. You edit message body fields from the JMS Message BodyColumns tab of the Edit Tables dialog box.

Table 3-2. JMS Message Types

Message Type Descr ip tion

Message JMS source and target definitions should represent the message type Message when the source or

target messages only need to contain header and property fields. Messages of the type Message

cannot contain body fields.

TextMessage JMS source and target definitions should represent the message type TextMessage when the source

or target messages contain XML data. Source and target definitions that represent messages of the

type TextMessage contain a single body field and can have multiple property fields.

BytesMessage JMS source and target definitions should represent the message type BytesMessage when the

source or target messages contain a stream of uninterpreted bytes. Source and target definitions

that represent messages of the type BytesMessage contain a single body field and can have

multiple property fields.

MapMessage JMS source and target definitions should represent the message type MapMessage when the

source or target messages contain name/value pairs. Source and target definitions that represent

messages of the type MapMessage can contain any number of body and property fields.

Figure 3-1. Default JMS Source and Target Definitions

Figure 3-2shows the JMS Message Body Columns tab of the Edit Tables dialog box:

Figure 3-2. Edit Tables Dialog Box

8/12/2019 117282088-jms

40/102


When you edit a JMS source or target definition, you can a lso change the message type of thesource or target definition from the JMS Message Body Columns tab. When you change themessage type, the structure of the source or target definition changes automatically. Forexample, if you modify the source or target definition to represent the message typeTextMessage, the Designer automatically adds a body field to the source or target definition.

You can also add any number of property fields . For more information about editing JMSsource and target definitions, see Editing JMS Source and Target Definitions on page 26.

Figure 3-3shows JMS source and target definitions in TextMessage format:

For more information about JMS message fields, see JMS Message Structure on page 4. Formore information about JMS message types, see JMS Message Types on page 3.

Figure 3 2. Edit Tables Dialog Box

Figure 3-3. JMS Source and Target Definitions in TextMessage Format

Message Body Fields

Message Property Fields

Message Header Fields

Working with Header Fields in a JMS Target

During a session, when the PowerCenter Server writes a value to the JMSDeliveryMode field

8/12/2019 117282088-jms

41/102

Overview 23

g , J yin the target, it writes 1 for non-persistent and 2 for persistent.

When the target is an MQSeries JMS provider, and the PowerCenter Server writes a value of

-1 to the JMSDeliveryMode field or JMSPriority field to the target, MQSeries JMS writes avalue of 4 to the field, and the session completes successfully.

Maintaining Transactional Consistency for JMS Targets

The PowerCenter Server can maintain transactional consistency when writing data to JMStargets. When the PowerCenter Server maintains transactional cons istency, it commitsmessages to JMS targets once all documents in a transaction group are loaded to the targets. Atransaction group consists of all documents that the PowerCenter Server commits when itreaches a commit point. If a session aborts or fails during a transaction, the PowerCenterServer rolls back all documents in the transaction group from the targets. When you enablerecovery and a session aborts or fails, you can restart the session in recovery mode. During arecovery session, the PowerCenter Server loads the documents to the targets.

To ensure transactional consistency, all JMS targets in the same pipeline must belong to thesame target connection group. JMS targets that are in the same target connection group

receive data from the same transactional source. Additionally, two or more JMS targets are inthe same target connection group if they have the same value for each of the followingconnection properties:

JNDI Context Factory

JNDI Provider URL

JNDI UserName

JNDI Password JMS Destination Type

JMS Connection Factory Name

For more information about source and target-based commits, see the PowerCenter WorkflowAdminis trat ion Guide. For more information about running sessions with transactionalconsistency, see Configuring Transactional Consistency for JMS Targets on page 41. Formore information about target connection groups, see the PowerCenter Workflow

Adminis trat ion Guide.

Creating a JMS Source Definition

8/12/2019 117282088-jms

42/102


You create a JMS source definit ion manually in the Designer.

To create a JMS source definition:

1. In the Source Analyzer, select Sources-Create.

The Create Source dialog box appears.

2. Enter a name for the source definition.

3. Enter a name in the Database name field.

4. From Database type, select JMS.

5. Click Create.

A JMS source definit ion appears in the Source Analyzer.

6. To add another source definition, enter a new source name. Click Create.

7. Click Done.

8. Choose Repository-Save.

Creating a JMS Target Definition

8/12/2019 117282088-jms

43/102

Creating a JMS Target Definition 25

You can create a JMS target definition manually in the Designer. You can also create a JMStarget definition based on a JMS source definition.

Manually Creating a JMS Target Definition

Use the following procedure to manually create a JMS target definition.

To create a JMS target definition:

1. In the Warehouse Designer, select Targets-Create.

The Create Target Table dia log box appears.

2. Enter a name for the target definition.

3. Select JMS as the database type.

4. Click Create.

A JMS target definition appears in the Warehouse Designer.

5. To add another target definition, enter a new target name. Click Create.

6. Click Done.


Creating a JMS Target Definition Based on a JMS Source Definition

Use the following procedure to create a JMS target definition based on a JMS sourcedefinition.

To create a JMS target definition based on a JMS source definition:

1. In the Warehouse Designer, drag a JMS source definition to the workspace.


Editing JMS Source and Target Definitions

8/12/2019 117282088-jms

44/102


You can edit JMS source and target definitions to add or modify columns to reflect changes insource or target messages. You can also modify the name and description of the source andtarget definitions. If you want to modify a source or target definition, you can do so from theEdit Tables dialog box.

If your source or target is MQSeries JMS, use the following guidelines when editing JMSsource and target definitions:

Property field names should not begin with JMS_.

Property and body field names should not begin with a number.

For more information about naming conventions of JMS message fields, see your JMS

provider documentation.

To edit JMS source and target definitions:

1. For source definitions, double-click the title bar of the source definition in the SourceAnalyzer. For target definitions, double-click the title bar of the target definition in theWarehouse Designer.

The Edit Tables window appears.

2. Optionally edit the following settings on the Table tab:

3. Click the JMS Message Header Columns tab.

4. Optionally edit the datatype and precision of the message header columns.

Table Sett ings EditSource/

TargetDescription

Select table Yes Both Displays the source or target definit ion you are editing. To choose a

different source or target definition to edit, select it from the list.

Rename button Yes Both Edit the name of the source or target definition.

Business name No Both Not applicable for JMS source or target definitions.

Owner name Yes Source Not applicable f or JMS source or target definitions.

Constraints Yes Target Not applicable t o JMS target definitions. Any entry is ignored.

Creation options Yes Target Not appl icable to JMS target defini tions. Any entry is ignored.

Desc ription Yes Both Optional description of the source or target def inition. Charact er limit is

2000 bytes/K, where K is the maximum number of bytes for eachcharacter in the PowerCenter repository code page. Enter links to

business documentation.

Database type No Both The database type is set to JMS.

Edit keywords Yes Target Add keywords to the target defini ti on. You can use the keywords to

perform searches in the Repository Manager.

Only some message header columns have editable datatype and precision. For moreinformation about JMS message header fields, see Message Header Fields on page 4.

5 For JMS target definitions optionally select the Not Null option for any message header

8/12/2019 117282088-jms

45/102

Editing JMS Source and Target Definitions 27

5. For JMS target definitions, optionally select the Not Null option for any message headerfield.

When you select the Not Null option, the field must contain a value when thePowerCenter Server writes messages to the target during the session. Otherwise, thePowerCenter Server generates an error for the field.

For some message header fields, you can configure values for the fields in the sessionproperties. For more information about configuring values for message header fields inthe session properties, see Configuring JMS Header Fields in the Session Properties onpage 41.

6. Click the JMS Message Property Columns tab.

7. Edit the message property fields as necessary:

To add a new property field, click the Add button. When you add a new field, you canchange the name, datatype, and precision of the field.

To remove a property field, click the Delete button. To change the order of property fields, use the up and down arrows.

For more information about JMS property fields, see Message Property Fields onpage 5.

8. For JMS target definitions, optionally select the Not Null option for any messageproperty field.

Move Column up

or down

Add Bu tton

Delete Button

When you select the Not Null option, the field must contain a value when thePowerCenter Server writes the message to the target during the session. Otherwise, thePowerCenter Server generates an error for the f ield.

8/12/2019 117282088-jms

46/102


When you l eave the Not Null option blank and the mapping does not contain a link tothe field in the target definition, the PowerCenter Server does not include the field in the

JMS target messages.

9. Click the JMS Message Body Columns tab.

10. Optionally choose one of the following message types from the Message Body Type list:

For more information about JMS message types, see Overview on page 20and JMSMessage Types on page 3.

JMS Message Type Descr ip tion

Message When you se lect Message, the Designer removes any body f ields f rom the source or

target definition.

TextMessage When you select TextMessage, the Designer removes any body f ie lds and adds a new

body field called BodyText to the source or target definition. Source and target

definitions in TextMessage format can only contain one body f ield.

BytesMessage When you select BytesMessage, the Designer removes any body fields and adds a new

body field called BodyBytes to the source or target definition. Source and targetdefinitions in BytesMessage format can only contain one body field.

MapMessage When you select MapMessage, the Designer removes any body f ie lds from the source or

target definition. However, you can add new body fields.

Move Column up

or down

Add But ton

Delete Button

11. For messages of the type MapMessage, edit the message body fields as necessary:

To add a new body field, click the Add button. When you add a new field, you canchange the name, datatype, and precision of the field.

8/12/2019 117282088-jms

47/102

Editing JMS Source and Target Definitions 29

To remove a body field, click the Delete button.

To change the order of the body fields, use the up and down arrows.

For more information about message body fields, see Message Body Fields on page 5.

12. For JMS target definitions, optionally select the Not Null option for any message bodyfield.

When you select the Not Null option, the field must contain a value when thePowerCenter Server writes messages to the target during the session. Otherwise, thePowerCenter Server generates an error for the field.

When you leave the Not Null option blank and the mapping does not contain a link tothe field in the target definition, the PowerCenter Server does not include the fie ld in the

JMS target messages.


Working with the Application Source Qualifier

An Application Source Qualifier in a mapping determines how the PowerCente r Server reads

8/12/2019 117282088-jms

48/102


An Application Source Qualifier in a mapping determines how the PowerCente r Server readsdata from the JMS source. When you run a session, the PowerCenter Server reads messagesfrom the JMS source based on the connected ports and transformation properties. To extractdata from multiple JMS sources, you must have an Application Source Qualifier for eachsource definition in the mapping.

Figure 3-4 shows a mapping with a JMS source definition connected to an Application SourceQualifier:

Creating an Application Source Qualifier

By default, the Designer creates an Application Source Qualifier when you add a JMS sourcedefinition to a mapping. If you configure the Designer to manually create a Source Qualifier

when you add a source definition to a mapping, you must manually connect an ApplicationSource Qualifier to a JMS source definition. For more information about manually

connecting Source Quali fiers to source definitions in a mapping, see the PowerCenterDesigner Guide.

Configuring an Application Source Qualifier

Once you create an Application Source Qualifier, you can set several configuration options.

To configure an Application Source Qualifier:

1. In the Designer, open a mapping.

2. Double-click the title bar of the Application Source Qualifier.

The Edit Transformations dialog box appears.

3. Click Rename, enter a descriptive name for the transformation, and click OK.

4. Click the Ports tab.

Figure 3-4. Mapping with a JMS Source Definition and an Application Source Qualifier

You may want to change numeric or date datatypes to string to maintain accuracy duringconversion. For more information, see JMS Datatype Reference on page 55.

5. Click the Properties tab.

8/12/2019 117282088-jms

49/102

Working with the Application Source Qualifier 31

6. Optionally modify the tracing level to set the amount of detail included in the session logwhen you run a se ssion containing this transformation.

7. Click OK to return to the Designer.

Transformation Datatypes

The transformation datatypes in the Application Source Qualifier are internal datatypes basedon ANSI SQL-92 generic datatypes, which PowerCenter uses to move data across platforms.

When the PowerCenter Server reads data from a JMS source, it converts the data from itsnative datatype to the transformation datatype. When you run a session, the PowerCenterServer performs transformations based on the transformation datatypes. When writing data toa target, the PowerCenter Server converts the data based on the native datatypes in the targetdefinition.

8/12/2019 117282088-jms

50/102


8/12/2019 117282088-jms

51/102

33

C h a p t e r 4

Creating and Configuring

JMS Workflows

This chapter includes the following topics:

Overview, 34

Working with JMS Workflows, 35 Configuring a Session with a JMS Mapping, 44

Scheduling Workflows, 51

Troubleshooting, 52

Overview

After you create mappings in the Designer, you can create a session and use the session in a

8/12/2019 117282088-jms

52/102

34 Chapter 4 : Creating and Conf igur ing JMS Workf lows

workflow to extract, transform, and load data. You create sessions and workflows in theWorkflow Manager.

Before configuring a JMS workflow, you must complete the following tasks:

Configure a registered server.You need to configure a registered server to run workflows.For more information about registering a server, see the PowerCenter Installation andConfiguration Guide.

Configure source and target connections.To read data from JMS or write data to JMSduring a workflow, you need to configure an application connection for JMS sources and

targets in the Workflow Manager. For more information about configuring connections,see Configuring Application Connection Properties on page 15.

Loading JVM During a Session Run

When you run a JMS workflow with a JMS session, the PowerCente r Server connects to JMSto read messages from a JMS source or write messages to a JMS target. When thePowerCenter connects to JMS during session initialization, it loads Java Virtual Machine

(JVM). The PowerCenter Server loads JVM once for each session run. The PowerCenterServer loads JVM once per session even if the session contains multiple JMS sources andtargets.

When you run multiple sessions with JMS mappings simultaneously, the sessions mayconsume more system resources.

Reading and Writing JMS Messages in SequenceJMS does not guarantee the delivery of messages in sequence. Therefore, when thePowerCenter Server reads messages from a JMS source, it may not read the messages in thesequence in which the source JMS provider sent the messages. Similarly, when thePowerCenter Server writes messages to a JMS target, the target JMS provider might notreceive messages in the order the PowerCenter Server wrote the messages to the target.

Working with JMS Workflows

When you configure a JMS workflow, you define the session and scheduler properties thatd h h C S d f S

8/12/2019 117282088-jms

53/102

Working with JMS Workflows 35

determine how the PowerCenter Server reads messages from a JMS source or writes messagesto a JMS target. You can configure the following JMS session and workflow properties:

Message filtering. Enter a filter condition to filter the messages from the source. For moreinformation, see Filtering Source Messages on page 35.

Session conditions. Set session conditions for a JMS session in a workflow. For moreinformation, see Configuring Session Conditions on page 36.

Real-time data extraction. Configure a JMS session in a workflow with the Real-timeFlush Latency session condition to extract data in real time. For more information, see

Real-time Flush Latency on page 38. Message recovery. Enable message recovery for a JMS session in a workflow. For more

information, see Message Recovery on page 39.

JMS target header fields. Configure values for header fields for JMS target messages. Formore information, see Configuring JMS Header Fields in the Session Properties onpage 41.

Transactional consistency.Configure transactional consistency for JMS targets. For more

information, see Configuring Transactional Consistency for JMS Targets on page 41. Pipeline partitioning.Set partitions in a pipeline for a JMS session in a workflow. For

more information, see Pipeline Partitioning on page 42.

Continuous workflows. Configure a scheduler with the continuous workflow schedulingproperty. For more information, see Configuring Continuous Workflows on page 42.

Filtering Source Messages

When you configure a JMS session in a workflow, you can enter a filter condition to f iltermessages from the source. You can filter messages by message header or message propertyfields. For example, you want to read messages from a JMS source with the topic stock.trade.

You also want to make sure that the messages contain the value buyin the property fieldTradeDescription. You can enter a filter condition to only read messages with the topicstock.tradeand the value buyin the TradeDescription property field from the source.

To filter messages from a JMS source, enter a filter condition for the Message Selectorattribute in the session properties. Specify a filter condition according to the JMS syntax inyour JMS documentation. If you do not enter a valid filter condit ion, the session fails duringinitialization.

For example, you can enter the following filter condition to read messages with the value buyin the property field TradeDescription:

TradeDescription = buy

Figure 4-1 shows the Properties settings on the Mapping tab (Sources node) where you enter amessage filter condition:

Figure 4-1. Message Selector in the Session Properties

8/12/2019 117282088-jms

54/102


Configuring Session Conditions

When you configure a JMS session in a workflow, you can set values for session conditions.You can define the following session conditions:

Idle Time

Message Count

Reader Time Limit

Real-time Flush Latency

The Idle Time, Message Count, and Reader Time Limit session conditions control when the

PowerCenter Server stops reading from JMS. The Real-t ime Flush Latency session conditioncontrols when the PowerCenter Server commits messages to the target for real-time dataextraction during the session.

Message

Selector: Use tofilter source

messages.

Figure 4-2shows the Properties settings on the Mapping tab (Sources node) where you setsession conditions:

Figure 4-2. Session Conditions in the Session Properties

8/12/2019 117282088-jms

55/102

Working with JMS Workflows 37

When you speci fy values for multiple session conditions, the PowerCenter Server stopsreading from JMS when the first session condition is met. For example, if you set the IdleTime value to 10 seconds and the Message Count value to 100 messages, the PowerCenter

Server stops reading from JMS after 10 seconds or after reading 100 messages, whichevercomes first.

Idle Time

Use the Idle Time session condition to indicate how long the PowerCenter Server waits whenno messages arrive before it stops reading from JMS. Specify an Idle Time value in seconds inthe session properties. For example, if you specify 30 for Idle Time, the PowerCenter Server

waits 30 seconds after reading from JMS. If no new messages arrive in JMS within 30 seconds,the PowerCenter Server stops reading from JMS.

Message Count

Use the Message Count session condition to control the number of messages the PowerCenterServer reads from JMS before stopping. Specify a Message Count value in the sessionproperties. For example, when you specify 100 for Message Count, the PowerCenter Server

reads 100 messages from JMS.

Session

Conditions

Reader Time Limit

Use the Reader Time Limit session condition to read messages from JMS for a set period oftime. When you use the Reader Time Limit session condition, the PowerCenter Server readsmessages from JMS for the time period you specify. Specify a Reader Time Limit value in

8/12/2019 117282088-jms

56/102


seconds in the session properties. For example, if you specify 10 for Reader Time Limit, the

PowerCenter Server stops reading from JMS after 10 seconds.

Real-time Flush Latency

Use the Real-time Flush Latency session condition in a session with a JMS source in themapping to run the session in real time. When you use the Real-time Flush Latency sessioncondition, the PowerCenter Server commits JMS source messages to the target at the end of aspecified maximum latency period. Specify a Real-time Flush Latency value in seconds in the

session properties.For example, if the value for Real-time Flush Latency is 5, the PowerCenter Server commitsall messages read from the source five seconds after the first message enters the source. Thelower you set the interval, the faster the PowerCenter Server commits messages to the target.

Note:When you specify a low Real-time Flush Latency interval, the session might consumemore system resources.

When you use the Real-time Flush Latency session condition to run a session in real time,take the following steps:

1. If the pipeline contains an XML target definition, select Create New Document orAppend to Document for the On Commit option from the Properties tab when you editthe target definition.

2. Configure the session for source-based commits in the session properties.

3. When you configure the session to use source-based commits and add partitions to the

pipeline, you must specify pass-through partitioning at each partition point.

4. Configure a real-time session to run as a continuous workflow. For more informationabout scheduling a workflow, see Scheduling Workflows on page 51.

When you set the Real-time Flush Latency session condit ion and configure the session to usesource-based commits, the PowerCenter Server commits messages to the target using thesource-based commit interval as well as the Real-time Flush Latency interval. For example,you use 5 seconds as the Real-time Flush Latency session condition and you set the source-

based commit interval to 1,000 messages. The PowerCenter Server commits messages to thetarget at two points: after reading 1,000 messages from the source and after each five secondReal-time Flush Latency interval.

If you configure the session to use target-based commits, the PowerCenter Serverautomatically runs the session using source-based commits. Also, it only commits messages tothe target based on the Real-time Flush Latency interval. It does not commit messages to thetarget based on the commit interval.

When the PowerCenter Server runs the session, it begins to read messages from the source.Once messages enter the source, the Real-time Flush Latency interval begins. At the end of

each five second Real-time Flush Latency interval, the PowerCenter Server commits allmessages read from the sourc

117282088-jms

Documents