Jms

User and Administrator Guide
Informatica PowerCenter
Connect
for JMS
(Version 7.1.1)
Informatica PowerCenter
Connect for JMS User and Administrator Guide

Version 7.1.1
August 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.
Tabl e of Contents iii
Table of Contents
List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
New Features and Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
PowerCenter Connect for JMS 7.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
PowerCenter Connect for JMS 7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
PowerCenter Connect for JMS 7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
About Informatica 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 . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Integrating PowerCenter with JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Designer Integration with JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
JMS Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
PowerCenter Server and JMS Integration . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 2: Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . 7
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Minimum System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Setting Paths on UNIX and Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Step 1. Set Library Paths for the PowerCenter Server . . . . . . . . . . . . . . . . 9
Step 2. Set the Path to the JVM Library File . . . . . . . . . . . . . . . . . . . . . 10
Configuring JVM Options for the PowerCenter Server . . . . . . . . . . . . . . . . . 11
Configuring JVM Options for the PowerCenter Server on Windows . . . . 11
iv Table of Contents
Configuring JVM Options for the PowerCenter Server on UNIX or
Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Registering JMS Provider Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Copying the JMS Provider Libraries to the PowerCenter Server
Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Setting the CLASSPATH to the JMS Provider Client Libraries in
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Registering the JMS Provider Client Libraries in UNIX or Linux . . . . . . 14
Configuring Application Connection Properties . . . . . . . . . . . . . . . . . . . . . 15
Connection Attributes for JNDI Application Connections . . . . . . . . . . . 15
Connection Attributes for JMS Application Connections . . . . . . . . . . . . 16
Configuring JNDI and JMS Application Connections . . . . . . . . . . . . . . 17
Chapter 3: Working with JMS Sources and Targets . . . . . . . . . . . . . 19
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . 33
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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
Tabl e of Contents v
Pipeline Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Configuring Continuous Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Configuring a Session with a JMS Mapping . . . . . . . . . . . . . . . . . . . . . . . . 44
Scheduling Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Appendix A: JMS Datatype Reference . . . . . . . . . . . . . . . . . . . . . . . . 55
Datatype Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
JMS and Transformation Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Boolean Datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Reading From JMS Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Appendix B: Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Using Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Appendix C: JMS Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
JMS Error Messages Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Designer Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Server Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
CMN Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
JMS Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
JSDK Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
TE Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
vi Table of Contents
List of Fi gures vii
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
viii Li st of Fi gures
Li st of Tabl es ix
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
x Li st of Tabl es
xi
Preface
Welcome to PowerCenter
Connect, Informaticas 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.
xii Preface
New Features and Enhancements
This section describes new features and enhancements to PowerCenter Connect for JMS 7.0,
7.1, and 7.1.1.
PowerCenter Connect for JMS 7.1.1
PowerCenter Connect for JMS 7.1.1 has the following new features and enhancements:
! Support for SuSe Linux. You can now install PowerCenter Connect for JMS for the
PowerCenter Server and Repository Server on SuSe Linux.
PowerCenter Connect for JMS 7.1
PowerCenter Connect for JMS 7.1 has the following new features and enhancements:
! 64-bit support. You can now run PowerCenter Connect for JMS on 64-bit AIX and HP-
UX (Itanium).
! Support for Red Hat Linux. You can now install PowerCenter Connect for JMS for the
PowerCenter Server and Repository Server on Red Hat Linux.
PowerCenter Connect for JMS 7.0
PowerCenter Connect for JMS 7.0 has the following new features and enhancements:
! Real-time processing enhancements. You can now use real-time processing in sessions that
also process active transformations, such as the Aggregator transformation. You can apply
the transformation logic to rows defined by transaction boundaries.
About Inf ormat ica Document ati on xi ii
About Informatica Documentation
The complete set of documentation for PowerCenter includes the following books:
! Data Profiling Guide. Provides information about how to profile PowerCenter sources 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.
xiv Preface
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

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

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

information to install PowerCenter Connect for TIBCO, build mappings, extract data
from TIBCO messages, and load data into TIBCO messages.
About Inf ormat ica Document ati on xv
PowerCenter
Connect for webMethods

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.
xvi Preface
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 Conventions
This guide uses the following formatting conventions:
If you see It means
italicized text
The word or set of words are especially emphasized.
boldfaced text
Emphasized subjects.
italicized monospaced text This is the variable name for a value you enter as part of an
operating system command. This is generic text that should be
replaced with user-supplied values.
Note: The following paragraph provides additional facts.
Tip: The following paragraph provides suggested uses.
Warning: The following paragraph notes situations where you can 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.
Other Informat ica Resources xvii
Other Informatica Resources
In addition to the product manuals, Informatica provides these other resources:
! Informatica Customer Portal
! Informatica Webzine
! Informatica web site
! Informatica Developer Network
! Informatica Technical Support
Visiting Informatica Customer Portal
As 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 Webzine
The 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 webzine@informatica.com.
Visiting the Informatica Web Site
You can access Informaticas 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
xviii Preface
The site contains information on how to create, market, and support customer-oriented add-
on solutions based on Informaticas interoperability interfaces.
Obtaining Technical Support
There are many ways to access Informatica technical support. You can call or email 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 Corporation
2100 Seaport Blvd.
Redwood City, CA 94063
Phone: 866.563.6332 or 650.385.5800
Fax: 650.213.9489
Hours: 6 a.m. - 6 p.m. (PST/PDT)
email: support@informatica.com
Informatica Software Ltd.
6 Waltham Park
Waltham Road, White Waltham
Maidenhead, Berkshire
SL6 3TN
Phone: 44 870 606 1525
Fax: +44 1628 511 411
Hours: 9 a.m. - 5:30 p.m. (GMT)
email: support_eu@informatica.com
Belgium
Phone: +32 15 281 702
Hours: 9 a.m. - 5:30 p.m. (local time)
France
Phone: +33 1 41 38 92 26
Germany
Phone: +49 1805 702 702
Netherlands
Phone: +31 306 082 089
Singapore
Phone: +65 322 8589
Hours: 9 a.m. - 5 p.m. (local time)
Switzerland
Phone: +41 800 81 80 70
Hours: 8 a.m. - 5 p.m. (local time)
1
C h a p t e r 1
Understanding PowerCenter
Connect for JMS
This chapter covers the following topics:
Overview, 2
Integrating PowerCenter with JMS, 3
2 Chapter 1: Understanding PowerCenter Connect for JMS
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.
I ntegrati ng PowerCenter with JMS 3
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 JMS
You 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 Types
The PowerCenter Server can read and write the following JMS message types:
Message. A Message does not contain message body fields. It contains only message 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.
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 Structure
JMS messages contain the following components:
Header
Properties
Body
Message Header Fields
JMS messages contain a fixed number of header fields. Each JMS message uses these 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.
I ntegrati ng PowerCenter with JMS 5
Message Property Fields
JMS 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 Fields
JMS 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 Integration
During 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.
Connecting to JMS Providers
When 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 Domains
The 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.
7
C h a p t e r 2
Installation and Configuration
This chapter includes the following topics:
! Overview, 8
! Setting Paths on UNIX and Linux, 9
! Configuring JVM Options for the PowerCenter Server, 11
! Registering JMS Provider Client Libraries, 14
! Configuring Application Connection Properties, 15
8 Chapter 2: Install ati on and Confi gurati on
Overview
PowerCenter Connect for JMS installs automatically with the PowerCenter Server, Client,
and Repository Server when you purchase the PowerCenter Real-time Option. To use
PowerCenter Connect for JMS, you must also install and configure a JMS provider, such 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 Requirements
Before 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.
Sett ing Paths on UNIX and Li nux 9
Setting Paths on UNIX and Linux
If you installed the PowerCenter Server on UNIX or Linux, complete the following steps:
1. Set library paths for the PowerCenter Server.
2. Set the path to the JVM library file.
Step 1. Set Library Paths for the PowerCenter Server
If you installed the PowerCenter Server on UNIX or Linux, you must set library paths for 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
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 File
Set 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
Conf iguri ng JVM Opti ons for the PowerCenter Server 11
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 Windows
Use 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.
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
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
Conf iguri ng JVM Opti ons for the PowerCenter Server 13
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
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
If the session fails due to a lack of memory, you may want to increase
this value.
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 Linux
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.
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
Confi guri ng Appl i cati on Connecti on Properti es 15
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 Connections
Configure a JNDI application connection to connect to a JNDI server during a workflow.
When the PowerCenter Server connects to the JNDI server, it 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
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 Connections
Configure 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
Confi guri ng Appl i cati on Connecti on Properti es 17
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 Connections
Use the following procedure to configure JNDI and JMS application connections.
To configure JNDI and JMS application connections:
1. In the Workflow Manager, connect to a PowerCenter repository.
2. Choose Connections-Application.
Table 2-6. JMS Application Connection Attributes
Connection 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.
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.
19
C h a p t e r 3
Working with JMS
Sources and Targets
This chapter covers the following topics:
Overview, 20
Creating a JMS Source Definition, 24
Creating a JMS Target Definition, 25
Editing JMS Source and Target Definitions, 26
Working with the Application Source Qualifier, 30
20 Chapter 3: Working with JMS Sources and Targets
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
Overvi ew 21
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
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
Overvi ew 23
Working with Header Fields in a JMS Target
During 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 Targets
The 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.
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.
Creat ing a JMS Target Defi ni ti on 25
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 Definition
Use the following procedure to manually create a JMS target definition.
To create a JMS target definition:
1. In the Warehouse Designer, select Targets-Create.
The Create Target Table 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 Definition
Use 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.
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.
Edit ing JMS Source and Target Def ini ti ons 27
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 Button
Delete Button
PowerCenter Server writes the message to the target during the session. Otherwise, the
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 Button
Delete Button
Edit ing JMS Source and Target Def ini ti ons 29
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.
PowerCenter Server writes messages to the target during the session. Otherwise, the
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.
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 Qualifier
By 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 Qualifier
Once you create an Application Source Qualifier, you can set several configuration options.
To configure an Application Source Qualifier:
1. In the Designer, open a mapping.
2. Double-click the title bar of the Application Source Qualifier.
The Edit Transformations dialog box appears.
3. Click Rename, enter a descriptive name for the transformation, and click OK.
4. Click the Ports tab.
Figure 3-4. Mapping with a JMS Source Definition and an Application Source Qualifier
Worki ng wi th the Appli cati on Source Qual if ier 31
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 Datatypes
The 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.
33
C h a p t e r 4
Creating and Configuring
JMS Workflows
This chapter includes the following topics:
Overview, 34
Working with JMS Workflows, 35
Configuring a Session with a JMS Mapping, 44
Scheduling Workflows, 51
Troubleshooting, 52
34 Chapter 4: Creating and Confi guri ng JMS Workflows
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 Run
When 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 Sequence
JMS 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.
Worki ng wi th JMS Workfl ows 35
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 Messages
When 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
Figure 4-1 shows the Properties settings on the Mapping tab (Sources node) where you enter a
message filter condition:
Configuring Session Conditions
When you configure a JMS session in a workflow, you can set values for session conditions.
You can define the following session conditions:
Idle Time
Message Count
Reader Time Limit
Real-time Flush Latency
The Idle Time, Message Count, and Reader Time Limit session conditions control when the
PowerCenter Server stops reading from JMS. The Real-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 Time
Use 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 Count
Use 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 Limit
Use 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.
Use 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 Recovery
You 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 Properties
You 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 Targets
The 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 Partitioning
If 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 Folder
When 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 Workflows
You 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.
Confi guri ng a Session wi th a JMS Mapping 45
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
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
Type
Commit
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.
Scheduli ng Workfl ows 51
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.
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.
Troubl eshooti ng 53
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.
55
A p p e n d i x A
JMS Datatype Reference
This appendix covers the following topics:
Datatype Reference, 56
56 Appendi x A: JMS Datatype Reference
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 Datatypes
When 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.
Datatype Reference 57
Boolean Datatype
When 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 Sources
When 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 Boolean
Byte
Byte Byte
Integer
Long
Short
String
Char Char
String
Table A-1. JMS and Transformation Datatypes
JMS Datatype
Transformation
Datatype
Range and Description
58 Appendi x A: JMS Datatype Reference
Double Double
String
Float Double
Float
String
Integer Integer
Long
String
Long Long
String
Short Integer
Long
Short
String
String Boolean
Byte
Double
Float
Integer
Long
Short
String
Table A-2. Source Datatypes and Compatible JMS Datatypes
Datatype in the Source Definition Datatype in a JMS Message
59
A p p e n d i x B
Code Pages
This appendix provides details about the following:
Using Code Pages, 60
60 Appendi x B: Code Pages
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.
61
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
62 Appendi x C: JMS Error Messages
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.
Desi gner Messages 63
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.
before importing.
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.
before importing.
The JMS body field name is invalid.
target definition from an XML file. However, a JMS body field name is
invalid. The XML file may have been modified.
before importing.
The JMS property field value is invalid.
target definition from an XML file. However, the value for a JMS property
field is invalid. The XML file may have been modified.
before importing.
Message body field is missing.
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.
before importing.
The object contains an invalid message body type.
target definition from an XML file. However, the XML file contains an invalid
message body type. The XML file may have been modified.
before importing.
The object has an invalid field category <category>.
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.
before importing.
The object has an invalid header field.
header field. The XML file may have been modified.
before importing.
Desi gner Messages 65
The object has an invalid header field map value.
map value for a header field. The XML file may have been modified.
before importing.
The object is a Bytes Message, but the body field name is invalid.
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.
before importing.
The object is a Bytes Message, but the datatype for the body field is invalid.
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.
before importing.
The object is a Text Message, but the body field name is invalid.
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.
before importing.
The object is a Text Message, but the datatype for the body field is invalid.
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.
before importing.
The precision is invalid.
target definition from an XML file. However, the precision for a field is
invalid. The XML file may have been modified.
before importing.
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 67
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 Codes
The 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.
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 Codes
The 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.
Server Messages 69
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.
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.
Server Messages 71
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.
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.
Server Messages 73
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.
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>.
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>.
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.
Server Messages 75
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.
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.
Server Messages 77
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.
JSDK Codes
The 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 Codes
The 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.
Server Messages 79
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.
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.
81
I n d e x
A
application connections
configuring 17
creating 17
description 15
JMS application connection 16
JNDI application connection 15
Application Source Qualifier
configuring 30
creating 30
datatypes 31
description 30
ASCII code page
writing JMS target data 60
B
BEA WebLogic Server
partitioning 42
C
code pages
See also PowerCenter Installation and Configuration
Guide
supported code pages 60
configuring
application connections 15
Application Source Qualifier 30
continuous workflows 42
library paths for the PowerCenter Server on UNIX or
Linux 9
path to the JVM library file on UNIX or Linux 10
registering JMS provider client libraries 14
sessions in a workflow 44
continuous workflows
configuring session slots 42
description 42
creating
application connections 15
JMS source definitions 24
JMS target definitions 25
D
datatypes
Boolean datatype 57
JMS 56
reading from JMS sources 57
transformation 56
documentation
conventions xvi
82 Index
description xiii
online xvi
E
editing
JMS source definitions 26
JMS target definitions 26
error messages
CMN codes 67
Designer messages 63
JMS codes 68
JSDK codes 78
overview 62
server messages 67
TE codes 78
F
filtering
source messages 35
I
Idle Time
configuring 48
description 37
Informatica
documentation xiii
Webzine xvii
installing
installation and configuration steps 8
J
JMS application connection
See also application connections
description 16
JMS message header fields
configuring in the session properties 41
troubleshooting 52
working with header fields in a JMS target 23
JMS provider
registering JMS provider client libraries 14
JMS source definitions
creating 24
editing 26
overview 20
JMS target definitions
creating 25
editing 26
overview 20
JMSDeliveryMode
working with the JMSDeliveryMode field in JMS
targets 23
JMSPriority
working with the JMSPriority field in JMS targets 23
JNDI application connection
See also application connections
description 15
JVM
loading during a session run 34
setting the path to the JVM library file on UNIX or
Linux 10
L
library paths
setting for the PowerCenter Server on UNIX or Linux
9
Load Manager
See also PowerCenter Workflow Administration Guide
M
Message Count
configuring 48
description 37
message recovery
description 39
enabling 49
specifying partitions and a recovery cache folder 42
using with certified messages 39
MQSeries JMS
naming property and body fields for an MQSeries JMS
source or target 26
troubleshooting 52
writing values to the JMSDeliveryMode field for
MQSeries JMS targets 23
writing values to the JMSPriority field for MQSeries
JMS targets 23
P
pipeline partitioning
BEA WebLogic Server 42
Index 83
description 42
specifying partitions and a recovery cache folder 42
PowerCenter Server
See also PowerCenter Installation and Configuration
Guide
property fields
troubleshooting 52
R
Reader Time Limit
configuring 49
description 38
configuring 49
configuring continuous workflows 42
configuring source-based commit 47
description 38
real-time sessions
configuring source-based commit 38
defined 38
setting the Real-time Flush Latency session condition
38
recovery
See message recovery
registered server
configuring 34
relational targets
configuring target load type 41
S
scheduling
workflows 51
session conditions
description 36
entering 36
Idle Time 37
Message Count 37
Reader Time Limit 38
Real-time Flush Latency 38
session logs
description 67
session properties
configuring JMS message header fields 41
sessions
configuring 44
loading JVM 34
source definitions
See JMS source definitions
source messages
filtering 35
T
target definitions
See JMS target definitions
target load type
selecting Normal mode for relational targets 41
troubleshooting
workflows 52
U
Unicode code page
reading JMS source data 60
W
webzine xvii
workflows
configuring sessions in a workflow 44
overview 34
scheduling 51
troubleshooting 52
84 Index

Jms

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Jms

Uploaded by

Copyright:

Available Formats

User and Administrator Guide

Connect for JMS User and Administrator Guide

Connect, Informaticas family of packaged software products that

Connect for JMS

is a natural extension to the open architecture of

Connect for JMS

User and Administrator Guide. Provides information

HIPAA Business Components User and Administrator Guide. Provides

Metadata Exchange SDK User Guide. Provides information about the

User Guide. Provides information on how to transport

Connect for IBM

User and Administrator Guide. Provides

Connect for MSMQ User and Administrator Guide. Provides information

Connect for PeopleSoft

User and Administrator Guide. Provides

Connect for SAP

BW User and Administrator Guide. Provides

Connect for SAP

Connect for SAP

User and Administrator Guide. Provides

Connect for Siebel

User and Administrator Guide. Provides information

Connect for TIBCO

User and Administrator Guide. Provides

Connect for webMethods

User and Administrator Guide. Provides

Connect for Web Services User and Administrator Guide. Provides

Connect Software Development Kit Developer Guide. Provides

You might also like