Informatica Development Platform (Version 9.1.0) Relational Data Adapter Guide

Transcription

1 Informatica Development Platform (Version 9.1.0) Relational Data Adapter Guide

2 Informatica Development Platform Relational Data Adapter Guide Version March 2011 Copyright (c) Informatica. All rights reserved. This software and documentation contain proprietary information of Informatica Corporation and are provided under a license agreement containing restrictions on use and disclosure and are 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. This Software may be protected by U.S. and/or international Patents and other Patents Pending. 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 and as provided in DFARS (a) and (a) (1995), DFARS (1)(ii) (OCT 1988), FAR (a) (1995), FAR , or FAR (ALT III), as applicable. The information in this product or documentation is subject to change without notice. If you find any problems in this product or documentation, please report them to us in writing. Informatica, Informatica Platform, Informatica Data Services, PowerCenter, PowerCenterRT, PowerCenter Connect, PowerCenter Data Analyzer, PowerExchange, PowerMart, Metadata Manager, Informatica Data Quality, Informatica Data Explorer, Informatica B2B Data Transformation, Informatica B2B Data Exchange, Informatica On Demand, Informatica Identity Resolution, Informatica Application Information Lifecycle Management, Informatica Complex Event Processing, Ultra Messaging and Informatica Master Data Management 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 and/or documentation are subject to copyright held by third parties, including without limitation: Copyright DataDirect Technologies. All rights reserved. Copyright Sun Microsystems. All rights reserved. Copyright RSA Security Inc. All Rights Reserved. Copyright Ordinal Technology Corp. All rights reserved.copyright Aandacht c.v. All rights reserved. Copyright Genivia, Inc. All rights reserved. Copyright 2007 Isomorphic Software. All rights reserved. Copyright Meta Integration Technology, Inc. All rights reserved. Copyright Oracle. All rights reserved. Copyright Adobe Systems Incorporated. All rights reserved. Copyright DataArt, Inc. All rights reserved. Copyright ComponentSource. All rights reserved. Copyright Microsoft Corporation. All rights reserved. Copyright Rogue Wave Software, Inc. All rights reserved. Copyright Teradata Corporation. All rights reserved. Copyright Yahoo! Inc. All rights reserved. Copyright Glyph & Cog, LLC. All rights reserved. Copyright Thinkmap, Inc. All rights reserved. Copyright Clearpace Software Limited. All rights reserved. Copyright Information Builders, Inc. All rights reserved. Copyright OSS Nokalva, Inc. All rights reserved. Copyright Edifecs, Inc. All rights reserved. This product includes software developed by the Apache Software Foundation ( and other software which is licensed under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. This product includes software which was developed by Mozilla ( software copyright The JBoss Group, LLC, all rights reserved; software copyright by Bruno Lowagie and Paulo Soares and other software which is licensed under the GNU Lesser General Public License Agreement, which may be found at The materials are provided free of charge by Informatica, "as-is", without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The product includes ACE(TM) and TAO(TM) software copyrighted by Douglas C. Schmidt and his research group at Washington University, University of California, Irvine, and Vanderbilt University, Copyright ( ) , all rights reserved. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (copyright The OpenSSL Project. All Rights Reserved) and redistribution of this software is subject to terms available at This product includes Curl software which is Copyright , Daniel Stenberg, <daniel@haxx.se>. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. The product includes software copyright ( ) MetaStuff, Ltd. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at license.html. The product includes software copyright , The Dojo Foundation. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at svn.dojotoolkit.org/dojo/trunk/license. This product includes ICU software which is copyright International Business Machines Corporation and others. All rights reserved. Permissions and limitations regarding this software are subject to terms available at This product includes software copyright Per Bothner. All rights reserved. Your right to use such materials is set forth in the license which may be found at kawa/software-license.html. This product includes OSSP UUID software which is Copyright 2002 Ralf S. Engelschall, Copyright 2002 The OSSP Project Copyright 2002 Cable & Wireless Deutschland. Permissions and limitations regarding this software are subject to terms available at This product includes software developed by Boost ( or under the Boost software license. Permissions and limitations regarding this software are subject to terms available at / This product includes software copyright University of Cambridge. Permissions and limitations regarding this software are subject to terms available at This product includes software copyright 2007 The Eclipse Foundation. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at This product includes software licensed under the terms at license.html, license.html, and This product includes software licensed under the Academic Free License ( the Common Development and Distribution License ( the Common Public License ( and the BSD License ( This product includes software copyright Joe WaInes, XStream Committers. All rights reserved. Permissions and limitations regarding this software are subject to terms available at This product includes software developed by the Indiana University Extreme! Lab. For further information please visit

3 This Software is protected by U.S. Patent Numbers 5,794,246; 6,014,670; 6,016,501; 6,029,178; 6,032,158; 6,035,307; 6,044,374; 6,092,086; 6,208,990; 6,339,775; 6,640,226; 6,789,096; 6,820,077; 6,823,373; 6,850,947; 6,895,471; 7,117,215; 7,162,643; 7,254,590; 7,281,001; 7,421,458; 7,496,588; 7,523,121; 7,584,422; 7,720,842; 7,721,270; and 7,774,791, international Patents and other Patents Pending. 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. Informatica Corporation does not warrant that this software or documentation is error free. The information provided in this software or documentation may include technical inaccuracies or typographical errors. The information in this software and documentation is subject to change at any time without notice. NOTICES This Informatica product (the Software ) includes certain drivers (the DataDirect Drivers ) from DataDirect Technologies, an operating company of Progress Software Corporation ( DataDirect ) which are subject to the following terms and conditions: 1. THE DATADIRECT DRIVERS ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. 2. IN NO EVENT WILL DATADIRECT OR ITS THIRD PARTY SUPPLIERS BE LIABLE TO THE END-USER CUSTOMER FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR OTHER DAMAGES ARISING OUT OF THE USE OF THE ODBC DRIVERS, WHETHER OR NOT INFORMED OF THE POSSIBILITIES OF DAMAGES IN ADVANCE. THESE LIMITATIONS APPLY TO ALL CAUSES OF ACTION, INCLUDING, WITHOUT LIMITATION, BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS. Part Number: DP-DAG

4 Table of Contents Preface.... iv Informatica Resources.... iv Informatica Customer Portal.... iv Informatica Documentation.... iv Informatica Web Site.... iv Informatica How-To Library.... v Informatica Knowledge Base.... v Informatica Multimedia Knowledge Base.... v Informatica Global Customer Support.... v Chapter 1: Introduction to the Relational Data Adapter SDK Overview of the Relational Data Adapter SDK Architecture Installation Chapter 2: Building a Relational Data Adapter Overview of Building a Relational Data Adapter Step 1. Get the Adapter ID Step 2. Define the Adapter and Connection Attributes Writing the Code for the Adapter and Connection Attributes Compiling the Source Files Step 3. Define the Type System Step 4. Define the Run-time Behavior Step 5. Run the Plug-In Generator Utility Step 6. Create the Registration XML File Step 7. Deploy the Adapter Naming Convention Troubleshooting the Relational Data Adapter Chapter 3: Connection Attributes Connection Attributes Overview Pre-Defined Connection Attributes Connection Attribute Properties Custom Connection Attributes Updating the Connection Attributes of an Adapter Chapter 4: Connection Management User Interface Connection Management User Interface Overview Table of Contents i

5 Pages and Groups Labels and Tooltips Dependency Validation Properties File Chapter 5: Type System Type System Overview Native Types Native Type Properties Informatica Platform Types Database Metadata Data Source Operation Chapter 6: Run-time Behavior Run-time Behavior Overview Run-time Utility Functions Accessing Connection Attributes Writing to the Informatica Logs Converting Between Character Sets Overriding the Default Error Handling Error Action File Chapter 7: Plug-In Generator Utility Overview of the Plug-in Generator Plug-in Generator Syntax Chapter 8: Registration Registration Overview Registration Schema Definition Chapter 9: Data Adapter Example: Firebird Database Firebird Database Adapter Overview Firebird Adapter Requirements Firebird Adapter Components FirebirdDefn.java FirebirdDefn() updateconnectinfoattributetypes() getconnectionconsumerinfo() getconnectinfoupdatedconsumerinfo() validateattributes() getadapterinfo() getattributeupgradedvalues() ii Table of Contents

6 getdatatypeinfo() getconfigdso() FirebirdTypeSystem.java getadapterinfo() getdatatypes() getdatatypetoodbcmap() firebird.c Writing Diagnostic Data to the Informatica Logs Retrieving Connection Attributes Handling Array Write Operations Modifying the Default Error Handling Registration XML Firebird Adapter Build Scripts Deploying the Firebird Adapter Using the Firebird Adapter Appendix A: Relational Data Adapter API Component Hierarchy Adapter Component Hierarchy Connection Attribute Component Hierarchy Type System Component Hierarchy Index Table of Contents iii

7 Preface The Informatica Development Platform Data Adapter Guide provides information about the Data Adapter SDK and how to use it to develop relational database adapters for Informatica. It provides an example that you can use to develop a relational database adapter. The Data Adapter Guide is written for independent software vendors, consulting organizations, and developers who want to develop database adapters for the Informatica platform. This guide assumes you have a working knowledge of Informatica and are familiar with relational databases, ODBC, JDBC, and application programming interfaces. Informatica Resources Informatica Customer Portal As an Informatica customer, you can access the Informatica Customer Portal site at The site contains product information, user group information, newsletters, access to the Informatica customer support case management system (ATLAS), the Informatica How-To Library, the Informatica Knowledge Base, the Informatica Multimedia Knowledge Base, Informatica Product Documentation, and access to the Informatica user community. Informatica Documentation The Informatica Documentation team takes every effort to create accurate, usable documentation. If you have questions, comments, or ideas about this documentation, contact the Informatica Documentation team through at infa_documentation@informatica.com. We will use your feedback to improve our documentation. Let us know if we can contact you regarding your comments. The Documentation team updates documentation as needed. To get the latest documentation for your product, navigate to Product Documentation from Informatica Web Site You can access the Informatica corporate web site at The site contains information about Informatica, its background, upcoming events, and sales offices. You will also find product and partner information. The services area of the site includes important information about technical support, training and education, and implementation services. iv

8 Informatica How-To Library As an Informatica customer, you can access the Informatica How-To Library at The How-To Library is a collection of resources to help you learn more about Informatica products and features. It includes articles and interactive demonstrations that provide solutions to common problems, compare features and behaviors, and guide you through performing specific real-world tasks. Informatica Knowledge Base As an Informatica customer, you can access the Informatica Knowledge Base at Use the Knowledge Base to search for documented solutions to known technical issues about Informatica products. You can also find answers to frequently asked questions, technical white papers, and technical tips. If you have questions, comments, or ideas about the Knowledge Base, contact the Informatica Knowledge Base team through at KB_Feedback@informatica.com. Informatica Multimedia Knowledge Base As an Informatica customer, you can access the Informatica Multimedia Knowledge Base at The Multimedia Knowledge Base is a collection of instructional multimedia files that help you learn about common concepts and guide you through performing specific tasks. If you have questions, comments, or ideas about the Multimedia Knowledge Base, contact the Informatica Knowledge Base team through at KB_Feedback@informatica.com. Informatica Global Customer Support You can contact a Customer Support Center by telephone or through the Online Support. Online Support requires a user name and password. You can request a user name and password at Use the following telephone numbers to contact Informatica Global Customer Support: North America / South America Europe / Middle East / Africa Asia / Australia Toll Free Brazil: Mexico: North America: Standard Rate North America: Toll Free France: Germany: Israel: Italy: Netherlands: Portugal: Spain: Switzerland: or United Kingdom: or Toll Free Australia: New Zealand: Singapore: Standard Rate India: Standard Rate France: Germany: Netherlands: Preface v

9 vi

10 C H A P T E R 1 Introduction to the Relational Data Adapter SDK This chapter includes the following topics: Overview of the Relational Data Adapter SDK, 1 Architecture, 2 Installation, 3 Overview of the Relational Data Adapter SDK The Relational Data Adapter SDK allows a developer to extend the data connectivity of the Informatica platform to include relational data sources that are not currently supported by Informatica. Although Informatica supports generic ODBC connectivity and allows access to any data source that has a standards-compliant ODBC driver, there are advantages to building an adapter using the Relational Data Adapter API. In cases where there is no ODBC driver available, building an adapter using the Relational Data Adapter API may be the only solution. Building an adapter to access a relational database has the following advantages: Data type integrity. Imported metadata retains information relating to the database native type system and preserves metadata lineage, allowing for optimal data type conversions. Use of native database features. You can build an adapter to handle features that are specific to the relational database and that may not be commonly found in other databases. Choice of data access API. You can choose the most appropriate client API to access the relational database. User experience. References to the adapter within the Informatica tools use terminology that is familiar and meaningful to a user of that database. The Relational Data Adapter API is written in a combination of C and Java. The connection definition and management interfaces are in Java, The run-time connectivity interface is in C. 1

11 Architecture The following diagram illustrates how a relational data adapter works with the services and tools in the Informatica domain: The Mapping Service module of the Data Integration Service uses connection objects to connect to data sources when it runs a mapping, SQL data service, or a web service. The Developer tool uses the adapter Eclipse plug-in to create and update connections. The Administrator tool uses the adapter plug-in to create and update the connection management properties in the Administrator tool. When an end user creates a connection object in Informatica, the connection information is stored in the enterprise data registry (EDR) of the domain configuration repository. When an end user uses a data source in a mapping, the Model Repository Service stores the database metadata and data source operation information in the Model repository. 2 Chapter 1: Introduction to the Relational Data Adapter SDK

12 Installation The Relational Data Adapter SDK is part of the Informatica Development Platform (IDP). You can use the IDP installer to install the Relational Data Adapter SDK files. You can get the IDP installer from the following sources: Informatica Development Platform installation DVD. Informatica ships the Informatica SDKs on a separate DVD. Run the IDP installer to install the Informatica SDKs on the machine where you plan to do your development. Informatica electronic software download site. When you purchase an Informatica product and choose to download the software, you receive a site link, user ID, and password to access the Informatica electronic software download site. Follow the instructions on the download site to download the IDP installation file. Informatica Technology Network. If you are a registered user of the Informatica Technology Network, you can download the IDP installation file from the Informatica Development Platform page. When you download the file, the Informatica Development Network provides you with a password. Use this password when you extract the files from the download file. When you run the IDP installer, all Informatica SDKs are installed in the directory you specify. Provide the installation directory and follow the instructions for installation. After you install the Informatica SDKs, you can find the Relational Data Adapter SDK in the following directory: <IDPInstallationDir>/Adapter_SDK The Relational Data Adapter SDK installation includes the following components to assist you in developing an adapter for the Informatica platform: Relational Data Adapter API files. Source and library files of the Relational Data Adapter API. Plug-in generator utility. Utility to generate the adapter deployment files. Sample adapter for the Firebird database. Firebird is an open source relational database that runs on many OS platforms. The sample adapter includes the source code so you can use the example as a model for building an adapter. Relational Data Adapter API Reference. Online documentation for the Relational Data Adapter API specification. Relational Data Adapter Guide. This document provides overview information and usage details about the Relational Data Adapter SDK and the sample Firebird adapter. Note: When you install the Informatica services, the installer creates the following folder for the files and libraries required by third-party adapters built using the Informatica Development Platform APIs: <InformaticaInstallationDirectory>/services/shared/extensions After you build an adapter, you can create a subfolder under the /extensions folder for the adapter files. Installation 3

13 C H A P T E R 2 Building a Relational Data Adapter This chapter includes the following topics: Overview of Building a Relational Data Adapter, 4 Step 1. Get the Adapter ID, 5 Step 2. Define the Adapter and Connection Attributes, 5 Step 3. Define the Type System, 8 Step 4. Define the Run-time Behavior, 8 Step 5. Run the Plug-In Generator Utility, 8 Step 6. Create the Registration XML File, 8 Step 7. Deploy the Adapter, 9 Naming Convention, 10 Troubleshooting the Relational Data Adapter, 10 Overview of Building a Relational Data Adapter The Relational Data Adapter SDK provides interfaces and utilities to make it easy to build a relational database adapter for the Informatica platform. To build a relational data adapter, complete the following tasks: 1. Get the adapter ID and connection type name from Informatica. An adapter must have a unique ID to distinguish it from other adapters. Contact Informatica Global Customer Support to get an ID and connection type for the adapter you build. If you build an adapter that will not be distributed outside of your organization, you can create the adapter identifier and connection type without contacting Informatica. 2. Define the adapter and connection attributes. Define the basic adapter characteristics and set up the connection attributes. Create the adapter properties file to contain the display text strings for the connection attributes. 3. Define the type system for the adapter. Define the data types supported by the relational data source and the corresponding data types supported by Informatica. 4. Write the code to define the run-time behavior. Define the behavior of the adapter when it reads and writes to the relational data source. Optionally, define the error handling rules for the data adapter. 5. Run the plug-in generator utility (plugingenerator) to generate the files for deployment. 4

14 Use the adapter definition and type system jar files as input to the utility to generate files for deployment. 6. Create the registration XML file. The registration file provides information about the adapter to the Informatica services and tools. 7. Deploy the adapter. To deploy the adapter, copy the adapter files to the Informatica directories where they are required. Step 1. Get the Adapter ID Before you build an adapter, contact Informatica to get the following identifiers: Adapter ID. Informatica assigns a unique ID for each adapter in the Informatica platform. If you build more than one adapter, you must get a unique ID for each adapter. Use the adapter ID when you define the connection attributes and type system for the adapter. If the adapter is in development stage or will not be distributed outside of your organization, you can set up an adapter ID without contacting Informatica. The adapter ID must use the format relational.####, where #### is a number with a range of 0013 to Connection type. Informatica provides a unique connection type name for the adapter. The connection type is equivalent to an adapter name. If the adapter is in development stage or will not be distributed outside of your organization, you can set up a connection type without contacting Informatica. Step 2. Define the Adapter and Connection Attributes A relational data adapter requires a number of connection components to enable it to work properly with the services and tools in the Informatica domain. When you define the adapter and connection attributes, you must provide the following components: Adapter properties that identify and describe the adapter. Database metadata properties that describe the behavior of the data source. Connection attributes that the adapter requires to connect to the data source. Connection management properties that display in the Informatica services and tools. Adapter properties file to localize the connection management user interface. Writing the Code for the Adapter and Connection Attributes Extend the AbstractINFASDKAdapter class to define the adapter and connection attribute objects. Adapter Properties Override the AbstractINFASDKAdapter.getAdapterInfo() method which returns an SDKAdapterInfo object. Set the properties for the adapter. Step 1. Get the Adapter ID 5

15 The following table describes the adapter properties that you need to set: Property AdapterType Description For a relational database adapter, set this property to SDKAdapterTypeEnum.RELATIONAL. AdapterVersion A string in #.#.# format that describes the adapter version number. For example: ConnectionType InfaAdapterID ConnectionTypeDesc ConnectionDisplayName ConnectionPoolType A string which identifies the connection type of the adapter. Each adapter must have a unique connection type. The connection type is equivalent to the adapter name. If you distribute the adapter to other organizations, you must get the connection type from Informatica. A unique identifier for the adapter. An adapter must have a unique ID to distinguish it from other adapters in the domain configuration repository. If you distribute the adapter to other organizations, you must get the adapter ID from Informatica. Description of the adapter. Name to use to reference the adapter on the connection management user interfaces. Indicator for whether the adapter can participate in the connection pooling controlled by the Informatica platform. If the adapter connection pooling is controlled by the Informatica platform, set this property to SDKConnectionPoolEnum.PLATFORM_CONTROLLED. Otherwise, set it to SDKConnectionPoolEnum.NONE. Database Metadata Properties Override the AbstractINFASDKAdapter.getMetadataConnectionInfo() method which returns an SDKMetadataConnectionInfo object. The following table describes the database metadata properties that you need to set: Attribute Property CaseSensitive EscapeWildCards MetadataConnMethod MetadataDriverName CatalogSupported SchemaSupported Description Indicates whether the comparison of schema name and table name during database metadata import must be case-sensitive. Indicates whether the characters percent symbol (%) and underscore (_) must be preceded with an escape sequence to prevent them from being interpreted as wildcard characters. The connection method to use to connect the relational database. The connection method must be JDBC. Default is JDBC. Database driver used to connect to the relational database. Indicates whether the relational database supports the catalog concept. Indicates whether the relational database supports the schema concept. 6 Chapter 2: Building a Relational Data Adapter

16 Connection Attributes The connection attributes of an adapter determine how an adapter connects to a relational data source. Informatica services and tools connect to data sources based on the connection attributes you define for the adapter. The Relational Data Adapter API provides a set of pre-defined connection attributes that you can use for an adapter. You can use these pre-defined attributes or create custom connection attributes. Override the AbstractINFASDKAdapter.updateConnectInfoAttributeTypes() method to modify or add to the list of pre-defined connection attributes. The SDKConnectInfoAttributeTypes object represents the list of connection attributes for an adapter and the SDKConnectAttributeType object represents a single connection attribute. You can iterate through the list of connection attributes to modify the characteristics of each attribute based on the requirements of the adapter. For more information about connection attributes, see Chapter 3, Connection Attributes on page 12. Connection Management Properties Informatica services and tools provide connection management user interfaces, such as the Connection Preferences view in the Developer tool, to expose the adapter connection attributes to the end user. The Informatica services and tools that provide connection management user interfaces are called adapter consumers. Adapter consumers include the Administrator tool, Developer tool, and command line programs. The adapter must provide information about how the adapter consumer will display the connection attributes. The adapter consumer information include the grouping hierarchy, labels, and tooltips for the connection attributes and any dependencies and required validation. Use the getconnectionconsumerinfo() and getupdatedconnectionconsumerinfo() methods of the AbstractINFASDKAdapter class to define the connection management properties specific to the adapter consumers. You must provide a properties file that contains the adapter consumer information for the connection attributes that appear on the connection management user interfaces. For more information about connection management properties, see Chapter 4, Connection Management User Interface on page 17. Adapter Properties File Create a properties file to hold the page and group names, labels, and tooltips for the connection attributes that appear on the connection management user interfaces of the adapter consumers. To enable localization of the connection management user interface, create a separate properties file for each language required. For more information about the properties file, see Properties File on page 19. Compiling the Source Files When you compile the adapter definition and type system java files, add the following file paths to the classpath: <IDPInstallationDir>\Adapter_SDK\common\pluginGenerator\* <IDPInstallationDir>\Adapter_SDK\common\SDKInterfaces\* Step 2. Define the Adapter and Connection Attributes 7

17 Step 3. Define the Type System Each data type in the relational database must be categorized into one of the semantic types defined in the Relational Data Adapter API. Each native type must also be associated with an Informatica platform data type. Extend and implement the methods of AbstractSDKTypesystem class to define how native data types map to the Informatica platform data types. For more information about defining the type system for the adapter, see Chapter 5, Type System on page 20. Step 4. Define the Run-time Behavior The Relational Data Adapter API provides run-time functions to define the behavior of the adapter when it reads and writes data to the relational data source. You must write the code to define the behavior of the adapter in the run-time functions. The functions are modeled after the ODBC API functions to make them easy to understand and use. Implement all the functions required to define the behavior of the adapter. The Data Integration Service has a default response to errors returned by the run-time functions. You can modify this behavior by providing an error action file that defines the error level for a combination of status code and native error code. Implement the INFASQLGetErrorHandling() function to specify the error action file to use and whether to allow user modification. For more information about defining the run-time behavior of the adapter, see Chapter 6, Run-time Behavior on page 25. Step 5. Run the Plug-In Generator Utility The plug-in generator utility uses the components you create to generate additional adapter component files for deployment. You must deploy the components you create and the files generated by the utility to specific locations in the Informatica directory. Package the adapter classes and components into jar files and provide the names of the adapter classes and components you created in the previous steps as input to the plug-in generator. You must also provide the Eclipse bundle information for the Eclipse plug-in that the utility produces. For more information about the plug-in generator utility, see Chapter 7, Plug-In Generator Utility on page 30. Step 6. Create the Registration XML File Create a registration file to provide information about the adapter and the location of the adapter files to the Informatica services and tools. The registration file is an XML file and must have the following file name: com.informatica.registration.definitions.xml The format of the registration XML file follows the schema defined in com.informatica.registration.definitions.xsd. For more information about the registration file, see Chapter 8, Registration on page Chapter 2: Building a Relational Data Adapter

18 Step 7. Deploy the Adapter After you run the plug-in generator and create the registration XML file, you have all the components required to deploy the adapter. You can create an installation program to deploy the files to the correct directories in the Informatica directory. 1. Create a directory for the adapter in the Informatica extensions directory: INFA_HOME\services\shared\extensions\AdapterName 2. Copy the adapter files to the Informatica services and client directories where they are required. The following table lists the adapter files that you copy to the Informatica services directories: Adapter File - com.informatica.registration.definitions.xml - Adapter library file (AdapterName.dll or AdapterName.so) - AdapterNameDefn.jar - AdapterNameTypesystem.jar com.informatica.sdk.adapters.typesystem.relational.adapte rnametypesystem.seed.xml (produced by the plug-in generator) AdapterNameTypesystem.jar (produced by the plug-in generator) Informatica Installation Directory INFA_HOME\services\shared\extensions\AdapterName INFA_HOME\services\shared\bin Must be copied to the following directories: - INFA_HOME\services\ModelRepositoryService - INFA_HOME\services\DataIntegrationService \DataIntegrationService\WEB-INF\lib - INFA_HOME\services\AnalystService\AnalystTool \WEB-INF\lib The following table lists the adapter files that you copy to the Informatica client directory: Adapter File AdapterName_Version.jar (produced by the plug-in generator) Informatica Installation Directory INFA_HOME\clients\DeveloperClient\plugins 3. Add the class path of the JDBC driver that you use to import the database metadata to the environment variable INFA_JAVA_CMD_CLASSPATH. 4. Restart the Informatica domain. Step 7. Deploy the Adapter 9

19 Naming Convention A naming convention makes it easy to identify the files that belong to an adapter and the usage of those files. Use the following guidelines when you name the data adapter files: Select a name for the adapter. The adapter name is equivalent to the connection type of the adapter. If you develop an adapter for distribution outside of your organization, you must get the connection type from Informatica so that it does not conflict with the connection types of other adapters. If the adapter will not be distributed outside of your organization, you can select a connection type for the adapter without contacting Informatica. Use the adapter name as a prefix for the adapter file names. The adapter name is an alphanumeric string that can include the letters A to Z and a to z, and the numbers 0 to 9. The first character of the name must be a letter. Select a unique name to identify the company building the adapter. The company name is included in the package name for the adapter classes. The following table describes the recommended naming convention for adapter files: Component Package for the adapter definition and type system classes Adapter definition class Type system class Resource file for connection management user interface Run-time shared library Error handling action file Naming Format com.companyname.informatica.adapter.adaptername AdapterNameDefn AdapterNameTypesystem AdapterName.properties AdapterName.dll or AdapterName.so AdapterName.act Use the adapter name when you create a directory for the adapter in the Informatica /extensions directory: <InformaticaInstallationDirectory>/services/shared/extensions/AdapterName The registration XML file must have the following name: com.informatica.registration.definitions.xml Copy the registration XML file to the /extensions/adaptername directory to ensure that it is associated with the correct adapter. When you populate the SDKAdapterInfo object, use AdapterName as the argument to the settypesystemname() and setconnectiontype() methods. Troubleshooting the Relational Data Adapter When you test the adapter, you need to verify that it runs correctly in all Informatica services and tools. You can turn on debugging options and send error messages to the Informatica logs. 10 Chapter 2: Building a Relational Data Adapter

20 To turn on the debugging options in the Developer tool, perform the following steps: 1. Go to the following Informatica Developer tool directory: INFA_HOME\clients\DeveloperClient 2. Edit the run.bat file and verify that developer.exe starts with the clean and debug options: developer.exe -clean debug 3. Edit the.options file and set the following options: com.informatica.tools.adapters.ui.relational/debug=true com.informatica.tools.adapters.model.relational/debug=true com.informatica.tools.adapters.model.sdk.connection/debug=true com.informatica.tools.adapters.ui.datasources/debug=true com.informatica.tools.adapters.ui.relational.datasources/debug=true com.informatica.tools.adapters.ui.sdk.connection/debug=true 4. Start the Developer tool using the run.bat file with INFA_HOME\ clients\developerclient as the current directory. You can view the errors in the following log file: INFA_HOME\clients\DeveloperClient\workspace\.metadata\.log To troubleshoot connection management or metadata import problems that are unrelated to the Developer tool or that do not display explicit errors in the Developer tool, check the following logs: INFA_HOME\tomcat\logs\catalina.out INFA_HOME\tomcat\logs\node.log INFA_HOME\tomcat\logs\exceptions.log INFA_HOME\tomcat\logs\MRS\* To troubleshoot connection errors that are generated when you preview or run a mapping in the Developer tool, you can view the mapping logs from within the Developer tool. Alternatively, you can find all mapping service logs in the following directory: INFA_HOME\tomcat\bin\disLogs\ms Troubleshooting the Relational Data Adapter 11

21 C H A P T E R 3 Connection Attributes This chapter includes the following topics: Connection Attributes Overview, 12 Pre-Defined Connection Attributes, 12 Connection Attribute Properties, 15 Custom Connection Attributes, 15 Updating the Connection Attributes of an Adapter, 16 Connection Attributes Overview The adapter connection attributes determine the behavior and capabilities of an adapter when it connects to a data source. The list of connection attributes for an adapter can include attributes such as connection level encryption, connection pool settings, database user credentials, and other database-specific attributes. The Relational Data Adapter API provides a set of pre-defined connection attributes that you can use for the adapter. You can enable any of the pre-defined attributes to use for the adapter. When you enable a pre-defined attribute, you can set its default value or mark it as a required attribute. You can disable attributes that are not applicable to the relational database you want to connect to. You can also define custom connection attributes for the adapter. Define a custom attribute if the relational database has a connection requirement that is not represented by one of the pre-defined attributes. Pre-Defined Connection Attributes The Data Adapter API provides pre-defined connection attributes that are common to many relational databases. Use the pre-defined attributes to establish the capabilities of the adapter. In some cases, the pre-defined connection attributes are associated with a pre-defined behavior. Informatica expects the values provided for the pre-defined connection attributes to be as documented. For example, Informatica expects the environmentsql connection attribute to contain an SQL statement that will be run immediately after a connection to the data source is established. If the value of environmentsql is not an SQL statement, Informatica generates an error. In other cases, you must write the code to handle the connection attributes. For example, the Relational Data Adapter API provides the hostname connection attribute because a relational database is typically associated with 12

22 a host name. However, Informatica does not use the value of hostname for any operation. You must write the code to use the value of the hostname attribute. The following table describes the pre-defined connection attributes and indicates which attributes have a predefined behavior: Attribute version codepage connectstring domainname packetsize usetrustedconnection ownername schemaname hostname port connectionretryperiod enableparallelmode environmentsql username password Description Version number of the adapter. This attribute is required and must be enabled. Used by Informatica services and tools. Code page for the connection. Reserved for Informatica use. If you need to store code page information, create a custom attribute. Formatted connection string for the connection. Maximum length is 512 characters. Name of the database domain. Maximum length is 128 characters. Packet size of data sent across the network. Indicates whether to use a trusted connection. Name of the database owner. Maximum length is 128 characters. Name of the database schema. Maximum length is 128 characters. Host name for the relational database server. Maximum length is 128 characters. Port number for the database connection. Number of seconds within which to try to establish a connection before failing. Used by Informatica services and tools. Indicates whether to enable parallel query options, if the database supports it. SQL statement to be executed after the connection is established. Maximum length is characters. Used by Informatica services and tools. Name for the database user account. Maximum length is 128 characters. Used by Informatica services and tools. Password for the user account. Maximum length is 128 characters. The password is case sensitive. Used by Informatica services and tools. transactionsql SQL statement to be executed at the start of a new transaction. Maximum length is characters. Used by Informatica services and tools. metadataconnusername User name for the account to use to connect to the database for metadata import. Maximum length is 128 characters. Used by Informatica services and tools. metadataconnstring Connection string for the database connection for metadata import. Maximum length is 512 characters. Minimum length is 0. Used by Informatica services and tools. Pre-Defined Connection Attributes 13

23 Attribute metadataconndatastoretype metadataconnpassword enablequotes quotechar ispsvcname dbname useexternalauth Description Database type for metadata import. Maximum length is 128 characters. Reserved for Informatica use. Password for the user account to use to connect to the database for metadata import. Maximum length is 128 characters. Used by Informatica services and tools. Indicates whether quotes are enabled in the SQL String. Default is true. Used by Informatica services and tools. Quote character to use in the SQL String, if quotes are allowed. Used by Informatica services and tools. Reserved for Informatica use. Name of the database to connect to. Maximum length is 128 characters. Indicates whether external authentication is used. Default is false. externalauthattribute Attribute associated with the external authentication scheme. Maximum length is 128 characters. useencrypteddbconnection Indicates whether to use an encrypted database connection. Default is false. encryptionstring Encryption string to use for an encrypted database connection. Maximum length is 128 characters. usepool maxidletime minconnections poolsize connectiontype name Indicates whether to use the connection pool controlled by the Informatica platform. The adapter property ConnectionPoolType must be set to PLATFORM_CONTROLLED for this connection attribute to take effect. Default is true. Used by Informatica services and tools. Number of seconds that a connection can remain pooled but unused before being discarded. Zero means idle connections never expire. Default is 120 seconds. Used by Informatica services and tools. Minimum number of free connections that will be maintained in a connection pool at any given time. The minimum number of connections are not created at startup. Once the number of free connections reaches or goes beyond the minimum limit, then the connection pool will not shrink to a size below the minimum limit. Used by Informatica services and tools. Maximum number of free connections that will be maintained in a connection pool at any given time. When the number of free connections reaches the maximum limit, free connections starting with the oldest one are released so that the number of free connections does not exceed the size limit. The poolsize attribute does not set a limit to the number of connections that can be created. Default is 15 connections. Used by Informatica services and tools. Connection type of the adapter. Maximum length is 255 characters. Used by Informatica services and tools. Name of the connection. Maximum length is 128 characters. Used by Informatica services and tools. 14 Chapter 3: Connection Attributes

24 You can also override additional properties for a pre-defined attribute that are common to pre-defined and custom attributes. Connection Attribute Properties For each connection attribute that you define for an adapter, you can set a number of properties. The properties allow you to specify whether an attribute is required, provide the default, maximum, and minimum values, or specify a list of possible values for the attribute. You can override these properties for pre-defined attributes or set these properties for custom attributes. All connection management user interfaces, including command line programs, validate the values set for the properties of a connection attribute. The following table describes the properties of a connection attribute: Attribute Property isused attributedescription ismandatory defaultvalue maxlength minlength minrangevalue maxrangevalue validlist attributeclidisplayname Description Indicates whether the adapter uses the connection attribute. Set to true to include the connection attribute in the adapter. Set to false to exclude the connection attribute from the adapter. If this property is set to false, the connection attribute will be ignored by the adapter. The attribute values cannot be set or validated and the attribute cannot be displayed on the connection management user interface. Description of the connection attribute. Indicates whether a connection attribute is required and must have a value. Set to true if the connection attribute is required. Set to false if the attribute value can be null. If you set the ismandatory property to true but you do not display the attribute on the connection management user interface, you must set a default value for the attribute. Default value for the attribute. Maximum length of a character string. Minimum length of a character string. Lower limit of a numeric range. Upper limit of a numeric range. List of values allowed for the attribute. Option name for the connection attribute. This name is used when the attribute is passed as an option to an Informatica command line program. The display name cannot contain spaces. Custom Connection Attributes Connection Attribute Properties 15