Jms

User and Administrator Guide

Informatica PowerCenter® Connect for JMS(Version 7.1.1)

Informatica PowerCenter® Connect for JMS User and Administrator GuideVersion 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 agreement containing 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), FAR 12.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 to us 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 Washington University 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 information provided 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.

Table of Contents

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

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

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiNew 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 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

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

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

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

Visiting Informatica Customer Portal . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Visiting the Informatica Webzine . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

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

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

Obtaining Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Chapter 1: Understanding PowerCenter Connect for JMS . . . . . . . . .1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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 . . . . . . . . . . . . . . . . . . . . . .7Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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

Table of Contents iii

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 . . . . . . . . . . . . 16

Configuring JNDI and JMS Application Connections . . . . . . . . . . . . . . 17

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

Working with Header Fields in a JMS Target . . . . . . . . . . . . . . . . . . . . . 23

Maintaining Transactional Consistency for JMS Targets . . . . . . . . . . . . . 23

Creating 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 with the Application Source Qualifier . . . . . . . . . . . . . . . . . . . . . . 30

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

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

Transformation Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

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

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

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

Working with 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

iv Table of Contents

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 . . . . . . . . . . . . . . . . . . . . . . . . 55Datatype Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

JMS and Transformation Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

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

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

Appendix B: Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Using Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

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

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

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

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

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

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

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

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

Table of Contents v

vi Table of Contents

List of Figures

Figure 1-1. PowerCenter and JMS Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Figure 1-2. PowerCenter Server and JMS Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Figure 2-1. JNDI Connection Object Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Figure 2-2. JMS Connection Object Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Figure 3-1. Default JMS Source and Target Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Figure 3-2. Edit Tables Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

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

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

Figure 4-1. Message Selector in the Session Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

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

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

List of Figures vii

viii List of Figures

List of Tables

Table 1-1. JMS Message Header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

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

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

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

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

Table 2-5. JNDI Application Connection Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Table 2-6. JMS Application Connection Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

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

Table 3-2. JMS Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

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

Table A-1. JMS and Transformation Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

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

List of Tables ix

x List of Tables

Preface

Welcome to PowerCenter® Connect, Informatica’s family of packaged software products that helps you extract data and metadata from ERP and other third-party applications.

PowerCenter® Connect for JMS® is a natural extension to the open architecture of PowerCenter, 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.

xi

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.1PowerCenter Connect for JMS 7.1.1 has the following new features and enhancements:

♦ Support for SuSe Linux. You can now install PowerCenter Connect for JMS for the PowerCenter Server and Repository Server on SuSe Linux.

PowerCenter Connect for JMS 7.1PowerCenter 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 the PowerCenter Server and Repository Server on Red Hat Linux.

PowerCenter Connect for JMS 7.0PowerCenter 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 that also process active transformations, such as the Aggregator transformation. You can apply the transformation logic to rows defined by transaction boundaries.

xii Preface

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 to evaluate source data and detect patterns and exceptions.

♦ Designer Guide. Provides information needed to use the Designer. Includes information to help you create mappings, mapplets, and transformations. Also includes a description of the 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 database connections.

♦ PowerCenter® Connect for JMS® User and Administrator Guide. Provides information to 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 the Repository Manager or the pmrep command line program. Includes details on functionality available in the Repository Manager and Administration Console, such as creating and maintaining repositories, folders, users, groups, and permissions and privileges.

♦ Transformation Language Reference. Provides syntax descriptions and examples for each transformation function provided with PowerCenter.

♦ Transformation Guide. Provides information on how to create and configure each type of transformation in the Designer.

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

♦ Web Services Provider Guide. Provides information you need to install and configure the Web Services 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 Web Services, and Metadata Web Services.

♦ Workflow Administration Guide. Provides information to help you create and run workflows in the Workflow Manager, as well as monitor workflows in the Workflow Monitor. Also contains information on administering the PowerCenter Server and performance tuning.

♦ XML User Guide. Provides information to create PowerCenter definitions from XML, XSD, or DTD files, and relational or XML definitions. Includes information on running sessions with XML data. Also includes details on using the Midstream XML transformation to extract or generate XML within a pipeline.

About Informatica Documentation xiii

Documentation available with our other products includes:

♦ Informatica® HIPAA Business Components User and Administrator Guide. Provides information on how to install and configure HIPAA Business Components to read and generate valid HIPAA transactions.

♦ Informatica® Metadata Exchange SDK User Guide. Provides information about the second generation of Metadata Exchange interfaces for PowerCenter repositories.

♦ Metadata Exchange for Data Models User Guide. Provides information on how to extract metadata from leading data modeling tools and import it into PowerCenter repositories through Informatica Metadata Exchange SDK.

♦ Metadata Exchange for OLAP User Guide. Provides information on how to use export multi-dimensional metadata from PowerCenter repositories into the Hyperion Integration Server through Informatica Metadata Exchange SDK.

♦ Informatica PowerChannel® User Guide. Provides information on how to transport compressed and encrypted data through a secure channel.

♦ PowerCenter® Connect for IBM® MQSeries® User and Administrator Guide. Provides information to install PowerCenter Connect for IBM MQSeries, build mappings, extract data from message queues, and load data to message queues.

♦ PowerCenter® Connect for MSMQ User and Administrator Guide. Provides information to install PowerCenter Connect for MSMQ, build mappings, extract data from message queues, and load data to message queues.

♦ PowerCenter® Connect for PeopleSoft® User and Administrator Guide. Provides information to install PowerCenter Connect for PeopleSoft, extract data from PeopleSoft systems, build mappings, and run workflows to load PeopleSoft source data into a warehouse.

♦ PowerCenter® Connect for SAP® BW User and Administrator Guide. Provides information to install and configure PowerCenter Connect for SAP BW to load source data into an SAP Business Information Warehouse.

♦ PowerCenter® Connect for SAP® R/3® Analytic Business Components™ Guide. Provides information on installing and working with Analytic Business Components for PowerCenter Connect for SAP R/3, including descriptions of repository objects and how you can use them to load a data warehouse.

♦ PowerCenter® Connect for SAP® R/3® User and Administrator Guide. Provides information 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.

♦ PowerCenter® Connect for Siebel® User and Administrator Guide. Provides information to install PowerCenter Connect for Siebel, extract data from Siebel systems, build mappings, and run workflows to load Siebel source data into a data warehouse.

♦ PowerCenter® Connect for TIBCO™ User and Administrator Guide. Provides information to install PowerCenter Connect for TIBCO, build mappings, extract data from TIBCO messages, and load data into TIBCO messages.

xiv Preface

♦ PowerCenter® Connect for webMethods™ User and Administrator Guide. Provides information to install PowerCenter Connect for webMethods, build mappings, extract data from webMethods documents, and load data into webMethods documents.

♦ PowerCenter® Connect for Web Services User and Administrator Guide. Provides information to install PowerCenter Connect for Web Services, extract data from a web service source, transform data using a web service, and load data into a web service target.

♦ PowerCenter® Connect Software Development Kit Developer Guide. Provides information to install PowerCenter Connect SDK and build plug-ins to extract data from third-party applications and load data into third-party applications.

About Informatica Documentation xv

About this Book

The Informatica PowerCenter Connect for JMS User and Administrator Guide provides information 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 and developers 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 for other supporting applications. For additional information about related JMS issues, refer to your JMS documentation.

The material in this book is available in online help.

Document ConventionsThis 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 overwrite or 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.

xvi Preface

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 at http://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 user community.

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 Webzine is a password-protected site that you can access through the Customer Portal. The Customer Portal has an online registration form for login accounts to its 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 SiteYou can access Informatica’s corporate web site at http://www.informatica.com. The site contains information about Informatica, its background, upcoming events, and locating your closest sales office. You will also find product information, as well as literature and partner information. The services area of the site includes important information on technical support, training and education, and implementation services.

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

http://devnet.informatica.com

Other Informatica Resources xvii

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

Obtaining Technical SupportThere are many ways to access Informatica technical support. You can call or email your nearest 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 at http://my.informatica.com

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

Informatica Corporation2100 Seaport Blvd.Redwood City, CA 94063Phone: 866.563.6332 or 650.385.5800Fax: 650.213.9489Hours: 6 a.m. - 6 p.m. (PST/PDT)email: [email protected]

Informatica Software Ltd.6 Waltham ParkWaltham Road, White WalthamMaidenhead, BerkshireSL6 3TNPhone: 44 870 606 1525Fax: +44 1628 511 411Hours: 9 a.m. - 5:30 p.m. (GMT)email: [email protected]

BelgiumPhone: +32 15 281 702Hours: 9 a.m. - 5:30 p.m. (local time)

FrancePhone: +33 1 41 38 92 26Hours: 9 a.m. - 5:30 p.m. (local time)

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

NetherlandsPhone: +31 306 082 089Hours: 9 a.m. - 5:30 p.m. (local time)

SingaporePhone: +65 322 8589Hours: 9 a.m. - 5 p.m. (local time)

SwitzerlandPhone: +41 800 81 80 70Hours: 8 a.m. - 5 p.m. (local time)

xviii Preface

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

1

Overview

PowerCenter Connect for JMS integrates with JMS to extract data from JMS sources and write 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 to read 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 connects to a JMS provider. JMS providers are message-oriented middleware systems that can send and receive 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 JMS provider based on the message topic. When the PowerCenter Server writes JMS messages to the target during a session, it can write JMS messages to a message queue. Or, it can write messages to a JMS provider based on the message topic.

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

2 Chapter 1: Understanding PowerCenter Connect for JMS

Integrating PowerCenter with JMS

PowerCenter Connect for JMS enables the PowerCenter Server to read messages from JMS sources 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 you create a mapping, use the Workflow Manager to create a session and workflow for the mapping. When you run the workflow, the PowerCenter Server connects to JMS providers to read 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 and target definitions represent metadata for JMS messages. When you define a JMS source or target, you define the source or target to reflect the message structure of the JMS messages you want the PowerCenter Server to read or write according to the JMS message type.

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

♦ Message. A Message does not contain message body fields. It contains only message header and properties fields.

♦ TextMessage. A TextMessage contains a String object. JMS messages of this type can contain 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 type generally 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.

Integrating PowerCenter with JMS 3

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

For more information about JMS message types, see “Working with JMS Sources and Targets” on page 19.

JMS Message StructureJMS messages contain the following components:

♦ Header

♦ Properties

♦ Body

Message Header FieldsJMS messages contain a fixed number of header fields. Each JMS message uses these fields regardless of message type. Every JMS source and target definition includes a pre-defined set of header fields. For more information about the header fields in JMS source and target definitions, see “Working with JMS Sources and Targets” on page 19.

Table 1-1 describes 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 time at which 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.

JMSExpiration The amount of time in milliseconds the message remains valid to be received. The messages remain in memory during this period.

JMSPriority The priority of the message on a scale of 0-9. 0 is the lowest priority. 9 is the highest.

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


Message Property FieldsJMS source and target definitions can include JMS property fields. JMS property fields are optional fields that contain additional message header information. JMS providers use message properties in a JMS message to give provider-specific information. Additionally, applications using a JMS provider can add property fields with application-specific information to a message.

Message Body FieldsJMS source and target definitions can include a JMS message body. The message body contains one or more message body fields. The body is an optional component of a JMS message. Only certain types of JMS messages contain a message body.

PowerCenter Server and JMS IntegrationDuring a workflow, the PowerCenter Server connects to the Java Naming and Directory Interface (JNDI) server to determine connection information for the JMS provider that is the source or target for the JMS message data. Once the PowerCenter Server determines the connection 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 read messages from a JMS provider and write messages to a JMS provider according to the message topic. Or, it can read messages from a JMS provider queue and write messages to a JMS provider queue.

Figure 1-2 shows how the PowerCenter Server connects to the JNDI server and JMS providers during 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 JNDI server to retrieve connection information to connect to a JMS provider.

Integrating PowerCenter with JMS 5

Connecting to JMS ProvidersWhen you configure a workflow to read messages from a JMS provider or write messages to a JMS 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 a connection to the JMS provider. For example, a connection factory for an MQSeries JMS provider may contain information about a host name and port number for the provider.

♦ Destination. The destination contains information about message sources and destinations. 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 JNDI application connection, you set connection information that enables the PowerCenter Server to connect to the JNDI server.

You also configure a JMS application connection in the Workflow Manager. In the JMS application connection, you provide a connection factory name and a destination name. You also provide a domain for the messages.

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

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

Message DomainsThe PowerCenter Server can read messages from JMS sources and write messages to JMS targets 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 the PowerCenter Server reads messages using the PTP domain, it reads messages from the JMS provider message queue. When the PowerCenter Server writes messages using the PTP domain, it writes messages to a JMS provider message queue.

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


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

7

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 as IBM MQSeries JMS or BEA WebLogic Server. The administrators of these systems should perform 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 or upgrade to PowerCenter 7.1.1 with the PowerCenter Real-time Option. For more information, 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 library file. For more information, see “Setting Paths on UNIX and Linux” on page 9.

3. Configure JVM parameters for the PowerCenter Server. For more information, see “Configuring 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 messages from a JMS source and writes messages to a JMS target. For more information, see “Configuring 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 following tasks:

♦ Install Java Runtime Environment (JRE). Install JRE on the machine hosting the PowerCenter 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 the PowerCenter Server and register the JMS JAR files on the PowerCenter Server machine. For more information about your JMS provider, consult your JMS provider documentation. For more information about registering the JMS JAR files, see “Registering JMS Provider Client Libraries” on page 14.

8 Chapter 2: Installation and Configuration

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 ServerIf you installed the PowerCenter Server on UNIX or Linux, you must set library paths for JRE in your Java directory.

Table 2-1 describes 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

Operating System Shared Library Environment Variable

AIX LIBPATH

HP-UX SHLIB_PATH

Solaris LD_LIBRARY_PATH

Linux LD_LIBRARY_PATH

Shell To Modify Environment Variable

C shell setenv PATH <Java_library_path>: $PATH

Bourne shell PATH = <Java_library_path>; export PATH

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

Operating System Library Path

AIX <Java_home>/jre/lib<Java_home>/jre/bin<Java_home>/jre/classic

HP-UX <Java_home>/jre/lib<Java_home>/jre/lib/{PA_RISC|PA_RISC2.0}<Java_home>/jre/lib/{PA_RISC|PA_RISC2.0}/{classic|hotspot}<Java_home>/jre/lib/{PA_RISC|PA_RISC2.0}/native_threads

Enter PA_RISC or PA_RISC2.0 depending on the version of Java installed on your machine. To determine the Java version, enter the following:java -version

Sett ing Paths on UNIX and Linux 9

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 shell, enter the following:

LIBPATH = Java/jre/lib; export LIBPATH

Step 2. Set the Path to the JVM Library FileSet the path to the JVM library file on UNIX or Linux using the C shell or Bourne shell.

Table 2-3 describes 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, enter the 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 the following 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 new location.

Solaris <Java_home>/jre/lib

Linux <Java_home>/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 <JVM_library_file_path>:$PATH

Bourne shell PATH = <JVM_library_file_path>; export PATH

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

Operating System Library Path


Configuring JVM Options for the PowerCenter Server

Once you install the PowerCenter Server, you must configure JVM options, including the JVM 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 the PowerCenter Server, see the PowerCenter Installation and Configuration Guide.

Configuring JVM Options for the PowerCenter Server on WindowsUse the Informatica PowerCenter Server Setup to configure JVM options for the PowerCenter Server.

To configure JVM options for the PowerCenter Server on Windows:

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

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

3. Click the JVM Options tab.

Configuring JVM Options for the PowerCenter Server 11

4. Configure the following VM Options:

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. The utility 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 library file for the JVMDllPath configuration parameter.

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

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

VM Option Required/Optional Description

VM Location Required The absolute path to the jvm.dll file. Informatica recommends that you set the absolute path to the jvm.dll file in the Java \hotspot directory for best performance. When you change the jvm.dll file location, you must set 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 to increase this value.

MaxMemory Optional Set this value to increase the maximum amount of memory for JVM to use during a PowerCenter session. The default value is 64 MB.If the session fails due to an out of memory error, you may want to increase this value.

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

Operating System JVM Library Name

AIX libjvm.a

HP-UX libjvm.sl

Solaris libjvm.so

Linux libjvm.so


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

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

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

2. Enter the following JVM options:

Option Required/Optional Description

JVMDllPath Required The absolute path to the JVM library file. Informatica recommends that you enter the absolute path to the JVM library file in the Java /hotspot directory on HP-UX, Solaris, and Linux for best performance.When you change the JVM library file location, you must set the absolute path to the new location.

JVMClassPath 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.

JVMMinMemory 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 a lack of memory, you may want to increase this value.

JVMMaxMemory Optional Set this value to increase the maximum amount of memory for JVM to use during a PowerCenter session. The default value is 64 MB.If the session fails due to a lack of memory, you may want to increase this value.

Configuring JVM Options for the PowerCenter Server 13

Registering JMS Provider Client Libraries

To read JMS messages from JMS providers and write JMS messages to JMS providers, you must 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 JMS provider documentation.

To register the JMS provider libraries, you can copy the libraries to the PowerCenter Server directory, 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 <PowerCenter Server>/bin/javalib directory. When you install the PowerCenter Server, the installation program creates this directory.

For example, if you want to register the MQSeries JMS client library com.ibm.mq.jar on Windows, 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 the CLASSPATH 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 LinuxIf the JMS provider client libraries are not in the JRE /lib/ext directory, you must set the CLASSPATH to each JMS provider client library.

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

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


Configuring Application Connection Properties

Before the PowerCenter Server can extract data from JMS sources or write data to JMS targets, you must configure application connections for JMS sources and targets in the Workflow Manager. The PowerCenter Server uses application connections to connect to a JMS provider during a session to read and write JMS messages. The application connections you define in the Workflow Manager are saved in the PowerCenter repository.

You must configure two types of JMS application connections:

♦ JNDI application connection

♦ JMS application connection

Connection Attributes for JNDI Application ConnectionsConfigure a JNDI application connection to connect to a JNDI server during a workflow. When the PowerCenter Server connects to the JNDI server, it retrieves information from JNDI 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 connection properties in the Connection Object Definition dialog box. For more information about PowerCenter and JNDI integration, see “Connecting to JMS Providers” on page 6.

Figure 2-1 shows the Connection Object Definition dialog box for a JNDI application connection:

Figure 2-1. JNDI Connection Object Definition

Configuring Application Connection Properties 15

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

For more information about JNDI, see your JMS documentation.

Connection Attributes for JMS Application ConnectionsConfigure a JMS application connection to connect to JMS providers during a PowerCenter session to read source messages or write target messages. When you configure a JMS application connection, you specify connection properties the PowerCenter Server uses to connect to JMS providers during a PowerCenter session. Specify the JMS application connection properties in the Connection Object Definition dialog box.

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

Table 2-5. JNDI Application Connection Attributes

Connection Attributes Required/Optional Description

JNDI Context Factory Required Enter the name of the context factory that you specified when you defined the context factory for your JMS provider.

JNDI Provider URL Required Enter the provider URL that you specified when you defined the provider 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-6 describes the attributes that you configure for a JMS application connection:

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

Configuring JNDI and JMS Application ConnectionsUse 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 Attributes Required/Optional Description

JMS Destination Type Required Select QUEUE or TOPIC for the JMS Destination 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 message topic 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.

Configuring Application Connection Properties 17

The Application Connection Browser dialog box appears.

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 click the appropriate button.


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

19

Overview

JMS source and target definitions represent metadata for JMS messages. When the PowerCenter 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 Server writes messages to a JMS target during a workflow, it writes messages based on the format defined in the target definition.

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

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

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

JMS source and target definitions can also contain message property and body fields depending on which JMS message type the source or target definition represents. JMS source and 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 Field JMS Source Definition JMS Target Definition

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

20 Chapter 3: Working with JMS Sources and Targets

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

JMS sources and targets that you define represent 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 contain property fields. However, you can add property fields to the source definition since JMS messages of the type Message can contain property fields.

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

Once you create a JMS source or target definition, you can edit it to reflect changes in the source or target data. For example, you can change the JMS message type. You can edit JMS message header, property, or body fields. You can change the datatype and precision of message 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 Tables dialog 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 Body Columns tab of the Edit Tables dialog box.

Table 3-2. JMS Message Types

Message Type Description

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

Overview 21

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

When you edit a JMS source or target definition, you can also change the message type of the source or target definition from the JMS Message Body Columns tab. When you change the message type, the structure of the source or target definition changes automatically. For example, if you modify the source or target definition to represent the message type TextMessage, 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 JMS source and target definitions, see “Editing JMS Source and Target Definitions” on page 26.

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

For more information about JMS message fields, see “JMS Message Structure” on page 4. For more 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 TargetDuring a session, when the PowerCenter Server writes a value to the JMSDeliveryMode field in 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 a value of 4 to the field, and the session completes successfully.

Maintaining Transactional Consistency for JMS TargetsThe PowerCenter Server can maintain transactional consistency when writing data to JMS targets. When the PowerCenter Server maintains transactional consistency, it commits messages to JMS targets once all documents in a transaction group are loaded to the targets. A transaction group consists of all documents that the PowerCenter Server commits when it reaches a commit point. If a session aborts or fails during a transaction, the PowerCenter Server rolls back all documents in the transaction group from the targets. When you enable recovery and a session aborts or fails, you can restart the session in recovery mode. During a recovery session, the PowerCenter Server loads the documents to the targets.

To ensure transactional consistency, all JMS targets in the same pipeline must belong to the same 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 in the same target connection group if they have the same value for each of the following connection 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 Workflow Administration Guide. For more information about running sessions with transactional consistency, see “Configuring Transactional Consistency for JMS Targets” on page 41. For more information about target connection groups, see the PowerCenter Workflow Administration Guide.

Overview 23

Creating a JMS Source Definition

You create a JMS source definition 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 definition 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

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

Manually Creating a JMS Target DefinitionUse 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 dialog 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 DefinitionUse the following procedure to create a JMS target definition based on a JMS source definition.

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.


Creating a JMS Target Definition 25

Editing JMS Source and Target Definitions

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

If your source or target is MQSeries JMS, use the following guidelines when editing JMS source 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 Source Analyzer. For target definitions, double-click the title bar of the target definition in the Warehouse 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 Settings Edit Source/Target Description

Select table Yes Both Displays the source or target definition 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 for JMS source or target definitions.

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

Creation options Yes Target Not applicable to JMS target definitions. Any entry is ignored.

Description Yes Both Optional description of the source or target definition. Character limit is 2000 bytes/K, where K is the maximum number of bytes for each character 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 definition. You can use the keywords to perform searches in the Repository Manager.


Only some message header columns have editable datatype and precision. For more information 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 field.

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

For some message header fields, you can configure values for the fields in the session properties. For more information about configuring values for message header fields in the session properties, see “Configuring JMS Header Fields in the Session Properties” on page 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 can change 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” on page 5.

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

Move Column up or down

Add ButtonDelete Button

Edit ing JMS Source and Target Definitions 27

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

When you leave the Not Null option blank and the mapping does not contain a link to the 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 20 and “JMS Message Types” on page 3.

JMS Message Type Description

Message When you select Message, the Designer removes any body fields from the source or target definition.

TextMessage When you select TextMessage, the Designer removes any body fields 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 field.

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 target definitions in BytesMessage format can only contain one body field.

MapMessage When you select MapMessage, the Designer removes any body fields from the source or target definition. However, you can add new body fields.

Move Column up or down

Add ButtonDelete 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 can change the name, datatype, and precision of the field.

♦ 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 body field.

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

When you leave the Not Null option blank and the mapping does not contain a link to the field in the target definition, the PowerCenter Server does not include the field in the JMS target messages.


Edit ing JMS Source and Target Definitions 29

Working with the Application Source Qualifier

An Application Source Qualifier in a mapping determines how the PowerCenter Server reads data from the JMS source. When you run a session, the PowerCenter Server reads messages from the JMS source based on the connected ports and transformation properties. To extract data from multiple JMS sources, you must have an Application Source Qualifier for each source definition in the mapping.

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

Creating an Application Source QualifierBy default, the Designer creates an Application Source Qualifier when you add a JMS source definition 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 Application Source Qualifier to a JMS source definition. For more information about manually connecting Source Qualifiers to source definitions in a mapping, see the PowerCenter Designer Guide.

Configuring an Application Source QualifierOnce 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 during conversion. For more information, see “JMS Datatype Reference” on page 55.

5. Click the Properties tab.

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

7. Click OK to return to the Designer.

Transformation DatatypesThe transformation datatypes in the Application Source Qualifier are internal datatypes based on 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 its native datatype to the transformation datatype. When you run a session, the PowerCenter Server performs transformations based on the transformation datatypes. When writing data to a target, the PowerCenter Server converts the data based on the native datatypes in the target definition.

Working with the Application Source Qualif ier 31


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

33

Overview

After you create mappings in the Designer, you can create a session and use the session in a workflow to extract, transform, and load data. You create sessions and workflows in the Workflow 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 and Configuration Guide.

♦ Configure source and target connections. To read data from JMS or write data to JMS during 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 RunWhen you run a JMS workflow with a JMS session, the PowerCenter Server connects to JMS to read messages from a JMS source or write messages to a JMS target. When the PowerCenter connects to JMS during session initialization, it loads Java Virtual Machine (JVM). The PowerCenter Server loads JVM once for each session run. The PowerCenter Server loads JVM once per session even if the session contains multiple JMS sources and targets.

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

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

34 Chapter 4: Creating and Configuring JMS Workflows

Working with JMS Workflows

When you configure a JMS workflow, you define the session and scheduler properties that determine how the PowerCenter Server reads messages from a JMS source or writes messages to 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 more information, see “Filtering Source Messages” on page 35.

♦ Session conditions. Set session conditions for a JMS session in a workflow. For more information, see “Configuring Session Conditions” on page 36.

♦ Real-time data extraction. Configure a JMS session in a workflow with the Real-time Flush 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. For more information, see “Configuring JMS Header Fields in the Session Properties” on page 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 scheduling property. For more information, see “Configuring Continuous Workflows” on page 42.

Filtering Source MessagesWhen you configure a JMS session in a workflow, you can enter a filter condition to filter messages from the source. You can filter messages by message header or message property fields. 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 buy in the property field TradeDescription. You can enter a filter condition to only read messages with the topic stock.trade and the value buy in the TradeDescription property field from the source.

To filter messages from a JMS source, enter a filter condition for the Message Selector attribute in the session properties. Specify a filter condition according to the JMS syntax in your JMS documentation. If you do not enter a valid filter condition, the session fails during initialization.

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

TradeDescription = ‘buy’

Working with JMS Workflows 35

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

Configuring Session ConditionsWhen 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-time Flush Latency session condition controls when the PowerCenter Server commits messages to the target for real-time data extraction during the session.

Figure 4-1. Message Selector in the Session Properties

Message Selector: Use to filter source messages.


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

When you specify values for multiple session conditions, the PowerCenter Server stops reading from JMS when the first session condition is met. For example, if you set the Idle Time 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, whichever comes first.

Idle TimeUse the Idle Time session condition to indicate how long the PowerCenter Server waits when no messages arrive before it stops reading from JMS. Specify an Idle Time value in seconds in the 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 CountUse the Message Count session condition to control the number of messages the PowerCenter Server reads from JMS before stopping. Specify a Message Count value in the session properties. For example, when you specify 100 for Message Count, the PowerCenter Server reads 100 messages from JMS.

Figure 4-2. Session Conditions in the Session Properties

Session Conditions


Reader Time LimitUse the Reader Time Limit session condition to read messages from JMS for a set period of time. When you use the Reader Time Limit session condition, the PowerCenter Server reads messages from JMS for the time period you specify. Specify a Reader Time Limit value in 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 LatencyUse the Real-time Flush Latency session condition in a session with a JMS source in the mapping to run the session in real time. When you use the Real-time Flush Latency session condition, the PowerCenter Server commits JMS source messages to the target at the end of a specified 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 commits all messages read from the source five seconds after the first message enters the source. The lower 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 consume more 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 or Append to Document for the On Commit option from the Properties tab when you edit the 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 information about scheduling a workflow, see “Scheduling Workflows” on page 51.

When you set the Real-time Flush Latency session condition and configure the session to use source-based commits, the PowerCenter Server commits messages to the target using the source-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 the target at two points: after reading 1,000 messages from the source and after each five second Real-time Flush Latency interval.

If you configure the session to use target-based commits, the PowerCenter Server automatically runs the session using source-based commits. Also, it only commits messages to the target based on the Real-time Flush Latency interval. It does not commit messages to the target 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 all messages read from the source. If the PowerCenter Server reads 1,000 messages before the end of a five second interval, it issues a source-based commit. It issues another commit when it reaches the FlushLatency interval. For more information about commit types and intervals, see the PowerCenter Workflow Administration Guide.

When you use the Real-time Flush Latency session condition, the following limitations apply:

♦ The pipeline cannot contain Transaction Control transformations.

♦ The pipeline cannot contain Custom transformations with the Generate Transaction option selected. You select the Generate Transaction option on the Properties tab of the Edit Transformations dialog box.

♦ The pipeline cannot contain transformations with the All Input option selected for the Transformation Scope property. You select a value for the Transformation Scope property on the Properties tab of the Edit Transformations dialog box.

♦ The pipeline cannot contain any transformation that has row transformation scope and receives input from multiple transaction control points.

♦ The mapping cannot contain a flat file target definition.

♦ The session cannot contain partition types other than pass-through at all partition points.

♦ The PowerCenter Server ignores the Real-time Flush Latency session condition when you run a session in debug mode.

♦ If your mapping contains a relational target, the Target Load Type attribute in the Properties settings on the Mapping tab (Targets node) in the session properties should be Normal.

Message RecoveryYou can configure message recovery for sessions that fail when reading messages from a JMS source. When you enable message recovery, the PowerCenter Server stores all messages it reads from the JMS source in a cache before processing the messages for the target. If the session fails, restart the session to recover the messages the PowerCenter Server could not process in the previous session run.

During the next session run, the PowerCenter Server reads the messages from the cache. After the PowerCenter Server reads the messages from the cache, it invokes the session conditions for the session and continues to extract messages from JMS. As a result, if you specify the Idle Time and Message Count session conditions for a session, the session conditions only apply to those messages the PowerCenter Server reads from JMS. They do not affect messages the PowerCenter Server reads from the cache.

The PowerCenter Server removes messages from the message cache file after the Real-time Flush Latency period expires. It also empties the cache file at the end of the session. If the session fails after the PowerCenter Server commits messages to the target but before it removes the messages from the cache file, targets may receive duplicate rows during the next session run.


To enable message recovery, do the following:

1. Select Enable Recovery on the Config Object tab in the session properties.

2. Specify a recovery cache folder in the session properties at each partition point.

Figure 4-3 shows the Properties settings on the Mapping tab (Sources node) where you specify a recovery cache folder:

When you enable message recovery, the following limitations apply:

♦ The JMS source definition cannot be a Joiner transformation master source.

♦ If you configure multiple JMS source definitions in the same target load order group for recovery, they cannot run concurrently.

♦ The mapping cannot contain an XML target definition.

♦ The session must include pass-through partition types at all partition points.

When you enable session recovery, the session may generate inconsistent data if you perform recovery under the following circumstances:

♦ The mapping uses a Normalizer transformation.

♦ The session performs incremental aggregation, and the PowerCenter Server stops unexpectedly.

♦ The PowerCenter Server data movement mode changes after the initial session failure.

♦ The PowerCenter Server code page changes after the initial session failure.

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

Recovery Cache Folder


♦ The PowerCenter Server runs in Unicode mode, and the user changes the session sort order.

♦ If the mapping contains a relational target, set the Target Load Type in the session properties to Normal to ensure incremental recovery during a recovery session. For more information about target load types, see the PowerCenter Workflow Administration Guide.

Warning: If you run a session with session recovery and the session fails, do not edit the cache or the mapping for the session before you restart the session.

Configuring JMS Header Fields in the Session PropertiesYou can configure a session to write values to target message header fields when the mapping does not pass data to the header fields in the JMS target definition. For example, you want to extract data from an XML source and write the data to a JMS target. The mapping transforms the source data and writes the data to a message body field in the JMS target. However, it does not pass data to the message header fields. You can configure the session properties to pass values to the target header fields.

You can configure values for the following message header fields:

♦ JMSReplyTo

♦ JMS Time Limit

♦ JMSDeliveryMode

♦ JMSPriority

♦ JMSType

If your mapping passes values to the message header fields in the target and your session configuration contains values for these fields, the PowerCenter Server overwrites the values in the session properties with the values in the target.

For more information about JMS message header fields, see “JMS Message Structure” on page 4 and “Overview” on page 20. For more information about configuring values for JMS message header fields in the session properties, see “Configuring a Session with a JMS Mapping” on page 44.

Configuring Transactional Consistency for JMS TargetsThe PowerCenter Server can maintain transactional consistency for JMS sessions with JMS sources and targets. With transactional consistency, the PowerCenter Server commits documents to JMS targets in transaction groups. If the session aborts or fails during a transaction, the PowerCenter Server rolls back all documents in the group from the targets.

Use the following guidelines when you configure transactional consistency:

♦ Select an application connection with the same connection properties for each JMS target in the pipeline. This ensures that all JMS targets in a single pipeline belong to the same target connection group.

♦ Configure source-based commits for the session.


♦ Set a commit interval to define the commit point for a transaction group.

For more information about transactional consistency in JMS mappings with JMS targets, see “Maintaining Transactional Consistency for JMS Targets” on page 23. For more information about target connection groups and source and target-based commits, see PowerCenter Workflow Administration Guide.

Pipeline PartitioningIf your JMS provider supports partitioning, you can increase the number of partitions in a pipeline to improve session performance. Increasing the number of partitions allows the PowerCenter Server to create multiple connections to sources and process partitions of sources and targets concurrently.

Note: When your JMS provider is WebLogic Server, you may only have one partition in a pipeline for the JMS source. Otherwise, the session fails.

When you create a session in a workflow, the Workflow Manager validates each pipeline in the mapping for partitioning. You can specify multiple partitions in a pipeline if the PowerCenter Server can maintain data consistency when it processes the partitioned data.

Table 4-1 describes the partition types for partition points in JMS mappings:

For more information about partitioning and a list of all partitioning restrictions, see the PowerCenter Workflow Administration Guide.

Specifying Partitions and a Recovery Cache FolderWhen you specify partitions for a JMS mapping in a session, and you configure the Recovery Cache Folder attribute in the session properties, enter a cache folder on a different device for each reader partition in the pipeline.

Configuring Continuous WorkflowsYou can schedule a JMS workflow to run continuously. A continuous workflow starts automatically when the Load Manager starts. When the workflow stops, it restarts immediately.

When you configure a continuous workflow, you must have enough session slots available for the Load Manager to run the session. If you do not set enough session slots in the Load Manager, the workflow can fail. To prevent the workflow from failing, disable the option to fail sessions if maximum number of concurrent sessions is reached. When the maximum

Table 4-1. Partition Types for Partition Points in JMS Mappings

Partition Point Partition Type

Application Source Qualifier for JMS sources Pass-through

JMS target All


number of sessions is reached, the session enters a pending session queue. The session runs when there is a session slot available and it is the next session in the queue scheduled to run.

You configure the Load Manager in the Informatica PowerCenter Server Setup application. For more information about configuring the Load Manager, see the PowerCenter Installation and Configuration Guide.

To schedule a continuous workflow, select Run Continuously from the Schedule tab in the scheduler properties when you schedule the workflow.



Configuring a Session with a JMS Mapping

When you configure a session using a JMS source or target, you need to set the following session properties:

♦ Connection type for Application Source Qualifiers for JMS sources

♦ Connection type for JMS targets

You can also configure the session with the following properties:

♦ Commit type and interval

♦ Error handling

♦ Message filter

♦ Session conditions

♦ Message recovery

♦ Message header properties for JMS target messages

♦ Transactional consistency

♦ Pipeline partitioning

To configure session properties for a JMS session:

1. In the Task Developer, double-click a JMS session to open the session properties.

The Edit Tasks dialog box appears.

2. From the Connections settings on the Mapping tab (Sources node), select a JNDI application connection for Application Source Qualifiers connected to JMS source definitions.

3. Select a JMS application connection value for Application Source Qualifiers connected to JMS source definitions.

For more information about configuring application connections, see “Configuring Application Connection Properties” on page 15.

JNDI Application Connection

JMS Application Connection

Configuring a Session with a JMS Mapping 45

4. From the Connections settings on the Mapping tab (Targets node), select a JNDI application connection for each JMS target definition.

Tip: If you configure the session for transaction consistency, verify that all JMS target definitions in a single pipeline belong to the same target connection group. For more information about configuring transaction consistency, see “Configuring Transactional Consistency for JMS Targets” on page 41. For more information about configuring application connections, see “Configuring Application Connection Properties” on page 15.

5. Select a JMS application connection value for each JMS target definition.

For more information about configuring application connections, see “Configuring Application Connection Properties” on page 15.

JNDI Application Connection

JMS Application Connection


6. From the General Options on the Properties tab, select Source as the commit type to extract data in real time and maintain transactional consistency for JMS targets.

For more information about running sessions in real time, see “Real-time Flush Latency” on page 38. For more information about maintaining transactional consistency, see “Configuring Transactional Consistency for JMS Targets” on page 41.

7. Optionally, edit the commit interval.

Commit TypeCommit Interval


8. From the Error Handling settings on the Config Object tab, optionally select a value for Stop on Errors.

When you select a value for Stop on Errors, the PowerCenter Server fails the session when it reaches the number of specified errors for the partition.

9. From the Properties settings on the Mapping tab (Sources node), optionally enter a message filter to filter messages from the JMS source.

For more information about filtering source messages, see “Filtering Source Messages” on page 35.

10. Optionally, edit the values for the Idle Time, Message Count, Reader Time Limit, and/or Real-time Flush Latency session conditions.

The Workflow Manager assigns the following default values to the session conditions:

Session Condition Default Value Description

Idle Time -1 JMS can remain idle for an infinite period of time before the PowerCenter session ends.

Message Count -1 The PowerCenter Server can read an infinite number of messages before the session ends.

Stop on Errors


For more information about session conditions, see “Configuring Session Conditions” on page 36.

11. Specify a value for the Recovery Cache Folder attribute if you want to enable message recovery.

The recovery cache folder directory must be on the machine running the PowerCenter Server.

The default directory is $PMCacheDir\.

12. Click the Properties settings on the Mapping tab (Targets node).

Reader Time Limit 0 The PowerCenter Server can read source messages from JMS for an infinite period of time.

Real-time Flush Latency 0 The PowerCenter Server does not run the session in real time.

Session Condition Default Value Description


13. Enter the following properties:

For more information about setting values for JMS message header fields for JMS targets in the session properties, see “Configuring JMS Header Fields in the Session Properties” on page 41.

14. Click OK to exit the session properties.

Properties Settings

Required/Optional Description

Send Interval Required The send interval is the minimum amount of time in milliseconds the PowerCenter Server waits between each message when writing messages to the target. For example, if you set the send interval to 2, the PowerCenter Server waits at least two milliseconds before writing messages to the target. The targets receive the messages once the PowerCenter Server issues a commit.If you stop the session during the session run, the PowerCenter Server waits until it writes the message it is processing to the target before stopping the session. Therefore, if you set a high value for Send Interval, the session may take longer to stop.The default value for the send interval is 0.

JMS Reply To*

Optional The name of the topic or queue. If you enter an invalid value, the session fails.

JMS Time Limit*

Required The time period in milliseconds target messages are valid after the PowerCenter Server writes the messages to the target. During this time period, JMS retains messages in memory. When the time limit expires, the target messages delete.When you enter a time limit value, the PowerCenter Server writes the value to the JMS Time Limit field in the JMS target messages.The default value for time limit is 0. This means that the PowerCenter Server retains target messages in memory for an infinite period of time.

JMS Delivery Mode*

Required Select Persistent or Non-Persistent for the delivery mode. If you select Persistent, the PowerCenter Server guarantees the delivery of JMS messages to the targets. If you select Non-Persistent, the PowerCenter Server attempts to deliver each JMS message to the targets, but does not guarantee delivery.

JMS Priority* Required Enter a value from 0 to 9 for the message priority. The higher you set the value, the greater priority the PowerCenter Server gives target messages when writing the messages to the target. The default value is 4.

JMS Type* Optional Enter a description of the message.

*If the mapping passes a value for any of these fields in the target, it overwrites the value you provide in the session properties.


Scheduling Workflows

Before you run a session in a workflow, you must configure and schedule the workflow. You can schedule a non-reusable scheduler for a workflow. Or, you can create a reusable scheduler to use with the workflow.

You can schedule a workflow to run continuously, run at a given time or interval, or you can manually start a workflow. The PowerCenter Server runs scheduled workflows through the duration of the schedule, unless a workflow fails. To run a continuous workflow, select Run continuously when you edit the scheduler for the workflow. For more information about scheduling workflows, see the PowerCenter Workflow Administration Guide.

Scheduling Workflows 51

Troubleshooting

I ran a session to write JMS messages to an MQSeries JMS provider. The session completed successfully, but the target messages do not contain any property fields.

When you configured the connection factory in JNDI for the MQSeries JMS provider, you set the TARGETCLIENT value to MQ. When MQSeries JMS receives target messages, it translates them to MQSeries message format. Messages in MQSeries format contain message header fields and a message body field. They do not contain property fields.

To receive target messages with property fields, set the value for TARGETCLIENT to JMS in your JNDI configuration, and run the session again. For information about the format of property fields in MQSeries JMS messages, see your MQSeries JMS documentation.

I ran a session to write data from an MQSeries JMS source to a JMS target. The session failed because the PowerCenter Server rejected data from the following header fields: JMSDestination, JMSReplyTo, and JMSMessageID.

When you have a mapping that passes JMS message header data from a JMS source to a JMS target and the source is MQSeries JMS, MQSeries JMS prepends data to the data in the JMSDestination, JMSReplyTo, and JMSMessageID message header fields.

For example, during a session, the PowerCenter Server writes data from the JMSDestination field in the source to the JMSDestination field in the target. The value for the JMSDestination field in the source is JMS_1. When the PowerCenter Server writes the data to the target, the value is queue://QM_pcserv/JMS_1. The PowerCenter Server rejects the message.

Use an Expression transformation in the mapping to extract the correct value and pass it to the target.

I ran a session to read data from a JMS source and write the data to a non-JMS target. The message ID value for the JMSMessageID field begins with “ID:” instead of only containing the message ID.

When you have a mapping that passes data from the JMSMessageID field in a JMS source to a non-JMS target, JMS includes the string “ID:” in the JMSMessageID field. To remove the “ID:” characters before the message ID, you must use an Expression transformation in the mapping.

I ran a session to write messages to an MQSeries JMS target. The commit interval for the session was high. The session failed due to a JMS exception. It failed to send messages to the MQSeries queue.

When you run a session with a high commit interval to write message to an MQSeries JMS target, the PowerCenter Server writes messages to MQSeries JMS. MQSeries JMS writes the messages to a cache file. Because the commit interval is high, the cache file might run out memory. As a result, the session fails. To prevent the session from failing, you can lower the commit interval. Or, you can increase the size of the MQSeries cache file.


I tried to run several sessions simultaneously to read messages from multiple JMS sources and write the messages to a single target. The sessions used the Idle time session condition and completed when the Idle Time condition was met. When the sessions completed, the session log reported that the PowerCenter Server only read a small number of messages from the source during some sessions.

When you run multiple sessions simultaneously to read messages from multiple JMS sources and write the messages to a single target, the PowerCenter Server may not read messages from the source for a few moments while it writes data to the target. As a result, the PowerCenter Server meets the Idle Time session condition and ends the session. To make sure that each session reads the appropriate number of messages, specify a higher value for the Idle Time session condition.

I tried to run a session to read messages from a JMS source. The session used the Enable Recovery session condition. The session failed. Before restarting the session in recovery mode, I edited the JMS source.

When you run a session to read messages from a JMS source or write messages to a JMS target, and the session uses the Enable Recovery session condition, you can restart the session in recovery mode. If you edit the JMS source or target during recovery mode, you might see the following message:

Failed to recover data from recovery cache. Reason: The requested datatype does not match the data written to the recovery cache. The cache may be corrupt.

To prevent the recovery session from failing, you must use the same JMS mapping that you used when the session failed. Or, if you modify the mapping, you can create a new session.

I receive the following error message when I run a JMS session with an MQSeries provider:

MAPPING> [JAVA PLUGIN] [ERROR] Unable to load message catalog - mqji

This error message displays even if the session completes successfully. To prevent the error message from displaying, include the <MQSeries JMS>\lib directory in the CLASSPATH.

Troubleshooting 53


A p p e n d i x A

JMS Datatype Reference

This appendix covers the following topics:

♦ Datatype Reference, 56

55

Datatype Reference

PowerCenter uses the following datatypes in JMS mappings:

♦ JMS datatypes. JMS datatypes appear in JMS source and target definitions in a mapping.

♦ Transformation datatypes. Transformation datatypes are generic datatypes that PowerCenter uses during the transformation process. They appear in all transformations in a mapping.

JMS and Transformation DatatypesWhen the PowerCenter Server reads data from a JMS source, it converts the data in the message header, message property, and message data fields to transformation datatypes used in the Application Source Qualifier transformation. When writing data to a JMS target, the PowerCenter Server converts the data based on the native datatypes in the target messages. The PowerCenter Server converts JMS data with JMS datatypes.

Table A-1 lists the JMS datatypes that PowerCenter supports and the corresponding transformation datatypes:

Table A-1. JMS and Transformation Datatypes

JMS Datatype Transformation Datatype Range and Description

Binary Binary 1 KB to 100 MB.You can pass binary data from a source to a target, but you cannot transform binary data.

Boolean String Unicode mode: Precision of 2 bytes.ASCII mode: Precision of 1 byte.

Byte Small Integer Precision of 5 and scale of 0.Integer value.

Char String Unicode mode: Precision of 2 bytes.ASCII mode: Precision of 1 byte.

Datetime Date/Time Jan 1, 1970 to Dec 31, 9999 AD.Combined date/time value with precision to the second.

Double Double Precision of 18 digits.

Float Real Precision of 7 digits.

Integer Integer Precision of 10 and scale of 0.Integer value.

Long Decimal Precision 1 to 28 digits and scale of 0.

56 Appendix A: JMS Datatype Reference

Boolean DatatypeWhen the PowerCenter Server reads data from a webMethods source field of the Boolean datatype, the PowerCenter Server converts the value “True” to “T” and the value “False” to “F.”

When the PowerCenter Server writes data to a webMethods target field of the Boolean datatype, it converts the value “T” to “True” and the value “F” to “False.” If the field contains any other value, the PowerCenter Server rejects the field.

Reading From JMS SourcesWhen you define datatypes for fields in JMS source messages, the datatypes must be compatible with datatypes for the corresponding field in the source definition. For example, if a property field called TradeAmount in a JMS message is of the datatype Long, the corresponding field in the source definition must be of the datatype Long or String.

When the source message contains a field that has a datatype that is not compatible with the datatypes for the corresponding field in the source definition, the PowerCenter Server generates an error for that field.

Table A-2 describes datatypes in source definitions and the datatypes they are compatible with in JMS messages:

Short Small Integer Precision of 5 and scale of 0.Integer value.

String String Unicode mode: (precision + 1) * 2.ASCII mode: precision + 1.1 to 65,535 characters.Fixed-length or varying-length string.

Table A-2. Source Datatypes and Compatible JMS Datatypes

Datatype in the Source Definition Datatype in a JMS Message

Binary Binary

Boolean BooleanByte

Byte ByteIntegerLongShortString

Char CharString

Table A-1. JMS and Transformation Datatypes

JMS Datatype Transformation Datatype Range and Description

Datatype Reference 57

Double DoubleString

Float DoubleFloatString

Integer IntegerLongString

Long LongString

Short IntegerLongShortString

String BooleanByteDoubleFloatIntegerLongShortString

Table A-2. Source Datatypes and Compatible JMS Datatypes

Datatype in the Source Definition Datatype in a JMS Message

58 Appendix A: JMS Datatype Reference

A p p e n d i x B

Code Pages

This appendix provides details about the following:

♦ Using Code Pages, 60

59

Using Code Pages

When you configure JMS and JNDI application connections in the Workflow Manager for a JMS source or target, the PowerCenter Server automatically selects a code page for the message data, which is the code page of the PowerCenter Server.

Warning: When you run a session to read data from a JMS source and the PowerCenter Server code page is Unicode, the JMS provider code page must also be Unicode. Similarly, when you run a session to write data to a JMS target and the PowerCenter Server code page is ASCII, the JMS provider code page must also be ASCII.

For a complete discussion of code page compatibility, see the PowerCenter Installation and Configuration Guide.

60 Appendix B: Code Pages

A p p e n d i x C

JMS Error Messages

This appendix provides details about the following:

♦ JMS Error Messages Overview, 62

♦ Designer Messages, 63

♦ Server Messages, 67

61

JMS Error Messages Overview

PowerCenter Connect for JMS returns messages when you perform tasks. Some messages are errors, and some are informational. You can use this chapter to help determine what causes error messages to appear and what measures you can take to correct the error.

When an error message is a result of an internal error, causes are listed when possible, but contacting our technical support is still the best recourse. For contact information, see “Obtaining Technical Support” on page xviii.

Messages from PowerCenter Connect for JMS can originate from the following:

♦ PowerCenter Designer

♦ PowerCenter Server

♦ JMS

♦ JMS providers

The Designer displays messages while importing source definitions and creating and validating mappings. The PowerCenter Server displays messages in the session log, server log, server event log, or workflow log.

Messages from JMS and JMS providers can display in conjunction with PowerCenter messages. When the PowerCenter Server receives an error from JMS or a JMS provider while reading source messages or writing target messages, the PowerCenter Server fails the session.

For more information about JMS error messages, see your JMS documentation. For more information about JMS provider error messages, see your JMS provider documentation. For other PowerCenter messages, see the PowerCenter Troubleshooting Guide.

62 Appendix C: JMS Error Messages

Designer Messages

The Designer displays messages in boxes, in the output window, and in the status bar as you perform a task. The messages in this section relate to JMS mappings in the Designer. This section lists messages alphabetically.

For more information about other error messages that appear in the Designer, see the PowerCenter Troubleshooting Guide.

The datatype assigned to the field <field name> is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, the datatype for the specified field in the XML file is invalid. The XML file may have been modified.

Action: Import the repository object from a new XML file. Avoid editing the XML file before importing.

Field <field name> is invalid because JMS source field does not allow "NOTNULL."

Cause: You wanted to import a repository object that represents a JMS source definition from an XML file. However, the specified field in the XML file is set to Not Null. The XML file may have been modified.


Header field <field name> is missing.

Cause: You wanted to import a repository object that represents a JMS source definition from an XML file. However, you attempted to import an XML file that represents a JMS target.

Action: If an XML file represents a JMS source definition, you must import it as a JMS source definition.

or

Cause: You wanted to import a repository object that represents a JMS target definition from an XML file. However, you attempted to import an XML file that represents a JMS source.

Action: If an XML file represents a JMS target definition, you must import it as a JMS target definition.

or

Cause: A header field is missing. The XML file may have been modified.


Designer Messages 63

The JMS body field name is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, a JMS body field name is invalid. The XML file may have been modified.


The JMS property field value is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, the value for a JMS property field is invalid. The XML file may have been modified.


Message body field is missing.

Cause: You wanted to import a repository object that represents a JMS source or target definition in Bytes message, Text message, or Map message format from an XML file. However, the XML file contains no body fields. The XML file may have been modified.


The object contains an invalid message body type.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, the XML file contains an invalid message body type. The XML file may have been modified.


The object has an invalid field category <category>.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, there is an invalid category for a message field in the XML file. The XML file may have been modified.


The object has an invalid header field.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, the XML file contains an invalid header field. The XML file may have been modified.



The object has an invalid header field map value.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, the XML file contains an invalid map value for a header field. The XML file may have been modified.


The object is a Bytes Message, but the body field name is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition in Bytes message format from an XML file. However, the body field name in the XML file is invalid. The XML file may have been modified.


The object is a Bytes Message, but the datatype for the body field is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition in Bytes message format from an XML file. However, the datatype for the body field in the XML file is invalid. The XML file may have been modified.


The object is a Text Message, but the body field name is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition in Text message format from an XML file. However, the body field name in the XML file is invalid. The XML file may have been modified.


The object is a Text Message, but the datatype for the body field is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition in Text message format from an XML file. However, the datatype for the body field in the XML file is invalid. The XML file may have been modified.


The precision is invalid.

Cause: You wanted to import a repository object that represents a JMS source or target definition from an XML file. However, the precision for a field is invalid. The XML file may have been modified.

Designer Messages 65


Unknown error happened.

Cause: The Designer encountered an unknown error. The Repository Server might not be running.

Action: Make sure the Repository Server is running. If necessary, start the Repository Server.

or

Cause: Your repository may contain inconsistencies.

Action: Contact Informatica Technical Support.


Server Messages

The PowerCenter Server writes error and informational messages in the session log. The PowerCenter Server on UNIX writes messages in the UNIX server log, pmserver.log, and the UNIX server error log, pmserver.err. The PowerCenter Server on Windows writes messages in the Windows Application Log, which you can view with the Event Viewer.

This section lists error messages specific to JMS sessions. For information about other error messages in the session log, see the PowerCenter Troubleshooting Guide.

CMN CodesThe following messages might appear when there are database errors, internal errors, and errors in memory allocation:

CMN_1764 Failed to delete file <filename>: Error Msg <error message>.

Cause: The PowerCenter Server could not delete the specified cache file.

Action: Check the additional error message for more information.

CMN_1765 Failed to open file <filename>: Error Msg <error message>.

Cause: The PowerCenter Server could not open the specified cache file.


CMN_1766 Failed to seek file <filename>: Error Msg <error message>.

Cause: Operating system error.

Action: Contact your internal technical support.

CMN_1767 Failed to ftell file <filename>: Error Msg <error message>.

Cause: Operating system error.

Action: Contact your internal technical support.

CMN_1768 Failed to truncate file <filename>: Error Msg <error message>.

Cause: The PowerCenter Server could not truncate the specified cache file.


CMN_1769 Inconsistent Guaranteed Message Delivery cache.

Cause: The message recovery cache file contains inconsistent data. A user might have modified the cache file. As a result, the PowerCenter Server may have lost message data used for message recovery.

Action: Do not modify the cache file.

or

Cause: Internal Error.

Server Messages 67


CMN_1770 Guaranteed Message Delivery cache consumer is registered more than once.

Cause: Internal Error.


CMN_1772 Guaranteed Message Delivery cache directory <directory name> does not exist.

Cause: The PowerCenter Server cannot find the cache file directory for message recovery.

Action: Verify that the cache file directory exists. Specify the correct path to the cache file directory in the session properties. If the cache file directory does not exist, create a directory and specify a directory path in the session properties.

CMN_1778 Failed to read file <file>: Error Msg <error message>.

Cause: The PowerCenter Server failed to read data from the specified cache file.


CMN_1779 Failed to write file <file>: Error Msg <error message>.

Cause: The PowerCenter Server failed to write data to the specified cache file.


CMN_1780 Guaranteed Message Delivery timestamp was changed, message cache will be cleaned and session will continue running.

Cause: This is an informational message. The JMS mapping or the session properties in the Task Developer are changed after the last session run. The message recovery cache will be deleted and the session will continue to run.

Action: None.

JMS CodesThe following messages might appear when there is a JMS error:

JMS_1001 Failed to connect to a JNDI provider: <error message>.

Cause: The PowerCenter Server could not connect to a JNDI provider.


JMS_1002 The object <object name> looked up from JNDI is not a Destination object.

Cause: The value for JMS Destination in the JMS application connection is not valid.

Action: Enter a valid value for JMS Destination. Use a value that exists in your JNDI configuration.


JMS_1003 Failed to set JMS exception listener: <error message>.

Cause: The PowerCenter Server cannot set a listener for JMS exceptions.


JMS_1004 The object <object name> is not a QueueConnectionFactory object in JNDI.

Cause: The value for JMS Connection Factory Name in the JMS application connection is not valid. The name of the connection factory is not a queue connection factory name in your JNDI configuration.

Action: Enter a valid queue connection factory name for the JMS Connection Factory Name attribute in the application connection.

JMS_1005 The object <object name> is not a TopicConnectionFactory object in JNDI.

Cause: The value for JMS Connection Factory Name in the JMS application connection is not valid. The name of the connection factory is not a topic connection factory name in your JNDI configuration.

Action: Enter a valid topic connection factory name for the JMS Connection Factory Name attribute in the application connection.

JMS_1006 The destination object is not a Queue object.

Cause: The value for the JMS Destination attribute in the JMS application connection is not a valid queue name. However, the value for JMS Destination Type in the application connection is QUEUE.

Action: Provide a valid queue name for the JMS Destination attribute. Make sure the queue name exists in your JNDI configuration.

or

Action: Change the Destination Type to TOPIC if the value for the JMS Destination attribute is a topic.

JMS_1007 The destination object is not a Topic object.

Cause: The value for the JMS Destination attribute in the JMS application connection is not a valid topic. However, the value for JMS Destination Type in the application connection is TOPIC.

Action: Provide a valid topic for the JMS Destination attribute. Make sure the topic exists in your JNDI configuration.

or

Action: Change the JMS Destination Type to QUEUE if the value for the JMS Destination attribute is a queue.

JMS_1008 Failed to create JMS connection: <error message>.

Cause: The PowerCenter Server cannot connect to JMS. As a result, the PowerCenter session failed.

Server Messages 69


JMS_1009 Failed to create JMS session: <error message>.

Cause: The PowerCenter Server cannot start a JMS session. As a result, the PowerCenter session failed.


JMS_1010 Failed to create JMS connection consumer: <error message>.

Cause: The PowerCenter Server cannot create a JMS connection consumer. As a result, the PowerCenter session failed.


JMS_1011 Failed to start JMS connection: <error message>.

Cause: The PowerCenter Server could not initialize a JMS connection. As a result, the PowerCenter session failed.


JMS_1012 Failed to stop JMS connection: <error message>.

Cause: The PowerCenter Server could not stop the JMS connection.


JMS_1013 Failed to close JMS connection: <error message>.

Cause: The PowerCenter Server could not close the JMS connection.


JMS_1014 Failed to close JNDI connection: <error message>.

Cause: The PowerCenter Server could not close the JNDI connection.


JMS_1015 Failed to look up object <object name> from JNDI.

Cause: The specified value in the JMS application connection is not valid. As a result, the session failed.

Action: Make sure the attribute value in the JMS application is valid. Make sure the value exists in your JNDI configuration.

or

Cause: The JNDI server may not be running.

Action: Verify that the JNDI server is running. If necessary, start the server.

JMS_1018 Cannot find message type from metadata extension.

Cause: JMS cannot find the message type represented in the source or target definition. The repository may contain inconsistencies.



JMS_1019 Cannot find JMS connection.

Cause: There may be no application connection specified for the Source Qualifier or target in the session properties.

Action: Specify a value for the application connection in the session properties.

or

Cause: The repository may contain inconsistencies.


JMS_1020 Failed to create the message consumer: <error message>.

Cause: JMS could not create the message consumer. The PowerCenter session failed.


JMS_1021 Failed to create the message consumer because of conflicting JMS session and JMS connection objects.

Cause: Internal error.


JMS_1022 Failed to get the JMS destination <destination>. Reason: <error message>.

Cause: The specified value for the JMS Destination attribute in the JMS application connection does not exist in your JNDI configuration.

Action: Configure JNDI to include the value. Or, use a value that exists in your JNDI configuration.

JMS_1023 Failed to get the Queue Connection Factory <queue connection factory>. Reason: <error message>.

Cause: The PowerCenter Server cannot retrieve the queue connection factory from JNDI to connect to JMS. The value for the JMS Connection Factory Name attribute may not be valid.

Action: Make sure the value for the JMS Connection Factory Name attribute is valid. Also, make sure the value exists in your JNDI configuration.

or


Action: Verify that the JNDI server is running. If necessary, start the JNDI server.

JMS_1024 Failed to get the Topic Connection Factory <topic connection factory>. Reason: <error message>.

Cause: The PowerCenter Server cannot retrieve the topic connection factory from JNDI to connect to JMS. The value for the JMS Connection Factory Name attribute may not be valid.

Server Messages 71

Action: Make sure the value for the JMS Connection Factory Name attribute is valid. Also, make sure the value exists in your JNDI configuration.

or


Action: Verify that the JNDI server is running. If necessary, start the JNDI server.

JMS_2002 Error in getting the session extension information for Source Qualifier <Source Qualifier name>.

Cause: The PowerCenter Server cannot read the session properties. The repository may contain inconsistencies.


JMS_2025 An error occurred while processing the message received by Source Qualifier <Source Qualifier name>. Reason: <error message>.

Cause: The PowerCenter Server could not process a message.


JMS_2026 JMS error occurred while processing the message received by Source Qualifier <Source Qualifier name>. Reason: <error message>.

Cause: The PowerCenter Server encountered a JMS error while processing a message.


JMS_2027 The data received is too large for processing the field <field name> by Source Qualifier <Source Qualifier name>. Reason: <error message>.

Cause: The PowerCenter Server cannot process data for the specified field. The data is too large.


JMS_2028 The message received by Source Qualifier <Source Qualifier name> does not match the body definition.

Cause: The PowerCenter Server received a message whose body fields do not match the source definition. The PowerCenter Server rejected the message.

Action: Make sure the body fields of the messages the PowerCenter Server reads from the source match the format of the source definition. Otherwise, the PowerCenter Server rejects the messages.

JMS_2029 The Source Qualifier <Source Qualifier name> encountered an error in closing the consumer. Reason: <error message>.

Cause: The PowerCenter Server could not close the JMS consumer.



JMS_2032 Unknown error occurred while writing the data to the DTM buffer by Source Qualifier <Source Qualifier name>. Reason: <error message>.

Cause: The PowerCenter Server encountered an unknown error during the session.


JMS_2035 The partition #<number> of Source Qualifier <Source Qualifier name> failed to get cache coordinator for recovery.



JMS_2036 File cache folder is not provided. Please enter a file cache folder.

Cause: You enabled message recovery for the session, but did not specify a file cache folder.

Action: In the session properties, enter a file cache folder.

JMS_2037 Failed to create storage information object for Guaranteed Message Delivery. Reason: <error message>.

Cause: You ran a session with message recovery enabled for the session. However, the session failed when the PowerCenter Server tried to write data to the recovery cache.


JMS_2038 Failed to register recovery cache. Reason: <error message>.

Cause: The PowerCenter Server could not register the session for message recovery.


JMS_2041 Failed to recover data from recovery cache. Reason: <error message>.

Cause: During a recovery session, the PowerCenter Server could not read messages from the recovery cache. As a result, the session failed.


JMS_2042 Unknown error encountered while recovering data from recovery cache.

Cause: During a recovery session, the PowerCenter Server encountered an unknown error. The cache might be corrupt.

Action: Remove the cache file. Run the session again.

JMS_2043 Failed to write data to recovery cache. Reason: <error message>.

Cause: During a recovery session, the PowerCenter Server could not write data to the recovery cache.


Server Messages 73

JMS_2044 Source Qualifier <Source Qualifier name> encountered an error while acknowledging the message. Reason: <error message>.

Cause: During a session to read messages from a JMS source, the PowerCenter Server encountered an error acknowledging a source message. As a result, the session failed.


JMS_2046 A data conversion error happened while processing the message for field <field name> in the Source Qualifier <Source Qualifier name>.

Cause: During a session to read messages from a JMS source, the PowerCenter Server could not process the specified field because of a data conversion error. The datatype for the field is not compatible with the datatype for the corresponding field in the source definition.

Action: Make sure that the datatype for the field in the JMS source messages is compatible with the datatype in the source definition. For more information about datatype compatibility, see Table A-2 on page 57.

JMS_2047 Message listener cannot be set: <error message>.

Cause: The PowerCenter Server cannot set the JMS message listener. As a result, the session failed.

Action: Verify that your JMS settings are correct. Check the additional error message for more information.

JMS_2048 Error closing JMS session: <error message>.

Cause: The JMS session cannot close.


JMS_2050 Source Qualifier <Source Qualifier name> encountered error while receiving the JMS message. Reason: <error message>.

Cause: During a session to read messages from a JMS source, the PowerCenter Server encountered a JMS error.


JMS_2051 The requested datatypes do not match the data written to the recovery cache. The cache may be corrupt.

Cause: The message recovery cache file may contain inconsistencies. The session failed.

Action: Manually delete the corrupted cache file.

JMS_2052 The jms.jar library could not be loaded.

Cause: The PowerCenter Server could not start the session because it could not load the jms.jar file.

Action: Verify that the jms.jar file is in the PowerCenter Server /bin/javlib directory.


JMS_3003 Cannot create writer connection: <error message>.

Cause: The PowerCenter Server cannot connect to JMS to write target messages.


JMS_3004 Cannot close connection: <error message>.

Cause: The PowerCenter Server cannot close the JMS connection.


JMS_3005 Cannot close JMS session: <error message>.

Cause: The JMS session cannot close.


JMS_3006 Cannot commit JMS session: <error message>.

Cause: The PowerCenter Server cannot commit messages to the JMS target.


JMS_3007 Cannot roll back JMS session: <error message>.

Cause: The PowerCenter Server could not roll back messages from the target.


JMS_3008 Cannot create JMS message object: <error message>.


or

Cause: Out of memory error.


or


JMS_3009 Cannot create message writer: <error message>.


or

Cause: Out of memory error.


or


JMS_3013 Cannot create a message object because an invalid message type is given.


Server Messages 75


JMS_3014 The field <field name> is not a valid JMS target field.

Cause: The repository may contain inconsistencies.


JMS_3015 An invalid row type was encountered. JMS writer will publish a message if the row type is INSERT, UPDATE, and DELETE only.

Cause: The row type for the source rows is Data Driven, but must be Insert, Update, or Delete.

Action: From the Properties tab in the session properties, set the value for the Treat Source Rows As property to Insert, Update, or Delete.

JMS_3016 JMS writer encountered an unknown row type error.

Cause: Your repository may contain inconsistencies.


JMS_3017 The value provided for <property name> in the JMS connection <connection name> is invalid. Reason: <error message>.

Cause: The value for the specified property is not valid.

Action: Provide a valid value for the property in the session properties.

JMS_3018 JMS writer encountered a JMS exception while field <field name> was being processed: <error message>.

Cause: The PowerCenter Server encountered a JMS exception while processing the specified field. The PowerCenter Server increased the error threshold as a result of the error.


JMS_3020 JMS writer encountered a data conversion error while field <field name> was being processed.

Cause: The PowerCenter Server could not convert the data for the specified field when writing messages to the JMS target. The field contains incompatible datatypes. The PowerCenter Server rejected the field.

Action: Make sure the datatypes in the target definition are compatible with JMS datatypes.

JMS_3021 JMS writer encountered a general exception: <error message>.

Cause: The JMS writer encountered an error. As a result, the session failed.


JMS_3022 JMS writer encountered a general error: <error message>.

Cause: The JMS writer encountered an error. As a result, the session failed.



JMS_3023 JMS exception happened in JMS provider: <error message>.

Cause: The target JMS provider encountered an error. As a result, the session failed.


JMS_3024 Invalid datatype ID: <error message>.



JMS_3025 JMS writer received NULL for the field <field name>, which is set to Not Null. The message will be rejected.

Cause: The specified field is set to Not Null in the target definition for the mapping.

Action: Edit the target definition in the Designer, and deselect the Not Null option for the field to prevent messages with a NULL value from being rejected.

JMS_3026 JMS writer encounters a JMS exception: <error message>.

Cause: The PowerCenter Server encountered a JMS error when writing messages to the target. As a result, the session failed.

Action: Check the additional error message for more information. If the additional error message is an MQSeries JMS message regarding an invalid value for the JMSTimeToLive field in the target, it prints the value for field multiplied by 1,000. For example, if the JMSTimeToLive value in the target is -1, the MQSeries JMS message prints -1,000.

JMS_3027 JMS writer encountered an out of memory error.

Cause: JVM is out of memory. As a result, the PowerCenter session failed.

Action: Increase the memory for JVM. Then, restart the session.

JMS_3028 JMS writer encountered an error in getting the default JMSReplyTo object <object name> from JNDI. Reason: <error message>.

Cause: The PowerCenter Server could not obtain a value for JMSReplyTo from JNDI.


JMS_3029 JMS writer encountered an error in processing the data for the field <field name> in the target <target name>. Reason: <error message>.

Cause: The PowerCenter Server could not process data for the specified field in the target.


Server Messages 77

JSDK CodesThe following message appears when you run a session to read or write JMS messages. If you receive any other message with the JSDK code, contact Informatica Technical Support.

JSDK_42021 Failed to load the library: <library name>.

Cause: You attempted to run a session to read messages from a JMS source or write messages to a JMS target. However, the JVM library is not properly set on the machine hosting the PowerCenter Server.

Action: If the PowerCenter Server runs on Windows, verify that the path to the jvm.dll file is properly set. You can do this from the Environment tab in the Systems settings on the Control Panel.

or

Action: If the PowerCenter Server runs on UNIX or Linux, make sure the library path for the JVM library is properly set. For more information about setting JVM library paths, see “Setting Paths on UNIX and Linux” on page 9.

TE CodesThe following messages relate to transformations used in the session:

TE_7109 Fatal Error: Mapping conflicts with RealTime commit.

Cause: The mapping contains two active sources in a pipeline. You cannot use two active sources in a pipeline for a real-time session.

Action: Use only one active source in a pipeline for a real-time session. For more information about active sources in a pipeline, see the PowerCenter Workflow Administration Guide.

TE_7111 Error: RealTime commit does not allow partition types other than pass-through for each partitioning point.

Cause: You selected a partition type other than pass-through for a partition point for a real-time session.

Action: When you run a real-time session, select pass-through partitioning at all partition points.

TE_7112 Error: Guaranteed Message Delivery does not allow XML targets in the mapping.

Cause: The session contains an XML target. When you enable message recovery for a session, you cannot use an XML target in the mapping.

Action: Use a target other than an XML target in the mapping for the session.

or

Action: Do not use message recovery for the session. To remove message recovery for the session, clear the Enable Recovery option in the session properties.


TE_7113 Error: Guaranteed Message Delivery does not allow mapping variables in the mapping.

Cause: The session contains mapping variables. When you enable message recovery for a session, you cannot use mapping variables in the mapping.

Action: Remove the mapping variables from the session.

or


TE_7114 Error: Guaranteed Message Delivery does not allow a dynamic lookup cache in the mapping.

Cause: The session contains a dynamic lookup cache. When you enable message recovery for a session, you cannot use a dynamic lookup cache in the mapping.

Action: Use a static lookup cache in a mapping for the session.

or


TE_7115 Error: The source configured for Guaranteed Message Delivery cannot be a Joiner transformation master source.

Cause: The session contains a mapping with a JMS source that is a Joiner master source. When you enable message recovery for the session, the source cannot be the Joiner master source.


TE_7116 Error: Guaranteed Message Delivery does not allow partition types other than pass-through for each partitioning point.

Cause: You enabled message recovery and selected a partition type other than pass-through for a partition point.

Action: When you enable message recovery, you must select pass-through partitioning at all partition points in the session properties.

or


TE_7117 Error: RealTime commit does not allow non-realtime SDK targets in the mapping.

Cause: You configured a session using Real-time Flush Latency as a session condition. However, the mapping contains an SDK target definition that you cannot use with real-time sessions.

Server Messages 79

Action: Enter 0 for the Real-time Flush Latency session condition.

TE_7131 Error: The transformation <transformation> is not configured to propagate transactions. Real-time is not supported.

Cause: You configured a session using Real-time Flush Latency as a session condition. However, the pipeline configuration prevents the session from being run in real time.

Action: If you do not want to run the session in real time, set the value for the Real-time Flush Latency session condition to 0.

or

Action: To run the session in real time, verify that your pipeline does not contain any of the above real-time limitations. For a list of real-time limitations, see “Real-time Flush Latency” on page 38.

TE_7135 Error: Recovery is enabled for more than one source in the concurrent source set. Recovery is not supported for such mappings. The sources enabled for GMD in the concurrent source set are: <source definition name>.

Cause: You attempted to perform session recovery on a mapping that contains one target load order group with multiple sources, and one or more of those sources is a real-time source. The real-time sources in the target load order group are connected to a multiple input group transformation or target.

Action: If the sources are connected to a Joiner transformation, you can enable the backward compatibility flag. The backward compatibility flag allows the PowerCenter Server to read sources connected to a Joiner transformation sequentially as it did in versions prior to 6.x.

or

Action: If the sources in the target load order group are connected to a multiple input group other than the Joiner transformation, disable session recovery. To remove message recovery for the session, clear the Enable Recovery option in the session properties.


I n d e x

Aapplication connections

configuring 17creating 17description 15JMS application connection 16JNDI application connection 15

Application Source Qualifierconfiguring 30creating 30datatypes 31description 30

ASCII code pagewriting JMS target data 60

BBEA WebLogic Server

partitioning 42

Ccode pages

See also PowerCenter Installation and Configuration Guide

supported code pages 60

configuringapplication connections 15Application Source Qualifier 30continuous workflows 42library paths for the PowerCenter Server on UNIX or

Linux 9path to the JVM library file on UNIX or Linux 10registering JMS provider client libraries 14sessions in a workflow 44

continuous workflowsconfiguring session slots 42description 42

creatingapplication connections 15Application Source Qualifier 30JMS source definitions 24JMS target definitions 25

Ddatatypes

Application Source Qualifier 31Boolean datatype 57JMS 56reading from JMS sources 57transformation 56

documentationconventions xvi

81

description xiiionline xvi

Eediting

JMS source definitions 26JMS target definitions 26

error messagesCMN codes 67Designer messages 63JMS codes 68JSDK codes 78overview 62server messages 67TE codes 78

Ffiltering

source messages 35

IIdle Time

configuring 48description 37

Informaticadocumentation xiiiWebzine xvii

installinginstallation and configuration steps 8

JJMS application connection

See also application connectionsdescription 16

JMS message header fieldsconfiguring in the session properties 41troubleshooting 52working with header fields in a JMS target 23

JMS providerregistering JMS provider client libraries 14

JMS source definitionscreating 24editing 26overview 20

JMS target definitionscreating 25editing 26overview 20

JMSDeliveryModeworking with the JMSDeliveryMode field in JMS

targets 23JMSPriority

working with the JMSPriority field in JMS targets 23JNDI application connection

See also application connectionsdescription 15

JVMloading during a session run 34setting the path to the JVM library file on UNIX or

Linux 10

Llibrary paths

setting for the PowerCenter Server on UNIX or Linux 9

Load ManagerSee also PowerCenter Workflow Administration Guide

MMessage Count


message recoverydescription 39enabling 49specifying partitions and a recovery cache folder 42using with certified messages 39

MQSeries JMSnaming property and body fields for an MQSeries JMS

source or target 26troubleshooting 52writing values to the JMSDeliveryMode field for

MQSeries JMS targets 23writing values to the JMSPriority field for MQSeries

JMS targets 23

Ppipeline partitioning

See also PowerCenter Workflow Administration GuideBEA WebLogic Server 42

82 Index

description 42specifying partitions and a recovery cache folder 42

PowerCenter ServerSee also PowerCenter Installation and Configuration

Guideproperty fields

troubleshooting 52

RReader Time Limit


Real-time Flush Latencyconfiguring 49configuring continuous workflows 42configuring source-based commit 47description 38

real-time sessionsconfiguring source-based commit 38defined 38setting the Real-time Flush Latency session condition

38recovery

See message recoveryregistered server

configuring 34relational targets

configuring target load type 41

Sscheduling

workflows 51session conditions

description 36entering 36Idle Time 37Message Count 37Reader Time Limit 38Real-time Flush Latency 38

session logsdescription 67

session propertiesconfiguring JMS message header fields 41

sessionsconfiguring 44loading JVM 34

source definitionsSee JMS source definitions

source messagesfiltering 35

Ttarget definitions

See JMS target definitionstarget load type

See also PowerCenter Workflow Administration Guideselecting Normal mode for relational targets 41

troubleshootingworkflows 52

UUnicode code page

reading JMS source data 60

Wwebzine xviiworkflows

See also PowerCenter Workflow Administration Guideconfiguring sessions in a workflow 44overview 34scheduling 51troubleshooting 52

Index 83

84 Index

Documents

Jms