Call Level Interface Guide and Reference Volume 1

Transcription

1 IBM DB for Linux, UNIX, and Windows Call Leel Interface Guide and Reference Volume 1 Updated January, 2013 SC

2

3 IBM DB for Linux, UNIX, and Windows Call Leel Interface Guide and Reference Volume 1 Updated January, 2013 SC

4 Note Before using this information and the product it supports, read the general information under Appendix B, Notices, on page 293. Edition Notice This document contains proprietary information of IBM. It is proided under a license agreement and is protected by copyright law. The information contained in this publication does not include any product warranties, and any statements proided in this manual should not be interpreted as such. You can order IBM publications online or through your local IBM representatie. To order publications online, go to the IBM Publications Center at order To find your local IBM representatie, go to the IBM Directory of Worldwide Contacts at planetwide/ To order DB2 publications from DB2 Marketing and Sales in the United States or Canada, call IBM-4YOU ( ). When you send information to IBM, you grant IBM a nonexclusie right to use or distribute the information in any way it beliees appropriate without incurring any obligation to you. Copyright IBM Corporation US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this book ii Chapter 1. Introduction to DB2 Call Leel Interface and ODBC Comparison of CLI and ODBC Chapter 2. IBM Data Serer CLI and ODBC driers IBM Data Serer Drier for ODBC and CLI oeriew 7 Obtaining the IBM Data Serer Drier for ODBC and CLI Installing the IBM Data Serer Drier for ODBC and CLI Configuring the IBM Data Serer Drier for ODBC and CLI Connecting to databases for ODBC and CLI.. 20 Running CLI and ODBC applications using the IBM Data Serer Drier for ODBC and CLI Deploying the IBM Data Serer Drier for ODBC and CLI with database applications Chapter 3. ODBC drier managers unixodbc drier manager Setting up the unixodbc drier manager Microsoft ODBC drier manager DataDirect ODBC drier manager Chapter 4. Initializing CLI applications 55 Initialization and termination in CLI oeriew Handles in CLI Chapter 5. Data types and data conersion in CLI applications String handling in CLI applications Large object usage in CLI applications LOB locators in CLI applications Direct file input and output for LOB handling in CLI applications LOB usage in ODBC applications Long data for bulk inserts and updates in CLI applications User-defined type (UDT) usage in CLI applications 69 Distinct type usage in CLI applications XML data handling in CLI applications - Oeriew 71 Changing of default XML type handling in CLI applications Chapter 6. Transaction processing in CLI oeriew Allocating statement handles in CLI applications.. 74 Issuing SQL statements in CLI applications Parameter marker binding in CLI applications Binding parameter markers in CLI applications 77 Binding parameter markers in CLI applications with column-wise array input Binding parameter markers in CLI applications with row-wise array input Parameter diagnostic information in CLI applications Changing parameter bindings in CLI applications with offsets Specifying parameter alues at execute time for long data manipulation in CLI applications Commit modes in CLI applications When to call the CLI SQLEndTran() function Preparing and executing SQL statements in CLI applications Deferred prepare in CLI applications Executing compound SQL (CLI) statements in CLI applications Cursors in CLI applications Cursor considerations for CLI applications Result set terminology in CLI applications Bookmarks in CLI applications Rowset retrieal examples in CLI applications.. 96 Retrieing query results in CLI applications Column binding in CLI applications Specifying the rowset returned from the result set Retrieing data with scrollable cursors in a CLI application Retrieing data with bookmarks in a CLI application Result set retrieal into arrays in CLI applications Data retrieal in pieces in CLI applications Fetching LOB data with LOB locators in CLI applications XML data retrieal in CLI applications Inserting data Inserting bulk data with bookmarks using SQLBulkOperations() in CLI applications Importing data with the CLI LOAD utility in CLI applications XML column inserts and updates in CLI applications Updating and deleting data in CLI applications Updating bulk data with bookmarks using SQLBulkOperations() in CLI applications Deleting bulk data with bookmarks using SQLBulkOperations() in CLI applications Calling stored procedures from CLI applications 120 CLI stored procedure commit behaior Creating static SQL by using CLI/ODBC static profiling Capture file for CLI/ODBC/JDBC Static Profiling Considerations for mixing embedded SQL and CLI Copyright IBM Corp iii

6 Freeing statement resources in CLI applications 128 Handle freeing in CLI applications Chapter 7. Terminating a CLI application Chapter 8. Trusted connections through DB2 Connect Creating and terminating a trusted connection through CLI Switching users on a trusted connection through CLI Chapter 9. Descriptors in CLI applications Consistency checks for descriptors in CLI applications Descriptor allocation and freeing Descriptor manipulation with descriptor handles in CLI applications Descriptor manipulation without using descriptor handles in CLI applications Chapter 10. Catalog functions for querying system catalog information in CLI applications Input arguments on catalog functions in CLI applications Chapter 11. Programming hints and tips for CLI applications Reduction of network flows with CLI array input chaining Chapter 12. Unicode CLI applications 161 Unicode functions (CLI) Unicode function calls to ODBC drier managers 163 Chapter 13. Multisite updates (two phase commit) in CLI applications ConnectType CLI/ODBC configuration keyword 165 DB2 as transaction manager in CLI applications 166 Process-based XA-compliant Transaction Program Monitor (XA TP) programming considerations for CLI applications Chapter 14. Asynchronous execution of CLI functions Executing functions asynchronously in CLI applications Chapter 15. Multithreaded CLI applications Application model for multithreaded CLI applications Mixed multithreaded CLI applications Chapter 16. Vendor escape clauses in CLI applications Extended scalar functions for CLI applications Chapter 17. Non-Jaa client support for high aailability on IBM data serers Non-Jaa client support for high aailability for connections to DB2 for Linux, UNIX, and Windows 194 Configuration of DB2 for Linux, UNIX, and Windows automatic client reroute support for non-jaa clients Example of enabling DB2 for Linux, UNIX, and Windows automatic client reroute support in non-jaa clients Configuration of DB2 for Linux, UNIX, and Windows workload balancing support for non-jaa clients Example of enabling DB2 for Linux, UNIX, and Windows workload balancing support in non-jaa clients Operation of the automatic client reroute feature when connecting to the DB2 for Linux, UNIX, and Windows serer from an application other than a Jaa application Operation of transaction-leel workload balancing for connections to DB2 for Linux, UNIX, and Windows Alternate groups for connections to DB2 Database for Linux, UNIX, and Windows from non-jaa clients Application programming requirements for high aailability for connecting to DB2 for Linux, UNIX, and Windows serers Client affinities for clients that connect to DB2 for Linux, UNIX, and Windows Non-Jaa client support for high aailability for connections to Informix serers Configuration of Informix high-aailability support for non-jaa clients Example of enabling Informix high aailability support in non-jaa clients Operation of the automatic client reroute feature when connecting to the Informix database serer serer from an application other than a Jaa application Operation of workload balancing for connections to Informix from non-jaa clients. 223 Application programming requirements for high aailability for connections from non-jaa clients to Informix database serer Client affinities for connections to Informix database serer from non-jaa clients Non-Jaa client support for high aailability for connections to DB2 for z/os serers Configuration of Sysplex workload balancing and automatic client reroute for non-jaa clients 233 Example of enabling DB2 for z/os Sysplex workload balancing and automatic client reroute in non-jaa client applications i Call Leel Interface Guide and Reference Volume 1

7 Operation of Sysplex workload balancing for connections from non-jaa clients to DB2 for z/os serers Operation of the automatic client reroute feature for an application other than a Jaa application to the DB2 for z/os serer Operation of transaction-leel workload balancing for connections to the DB2 for z/os data sharing group Alternate groups for connections to DB2 for z/os serers from non-jaa clients Application programming requirements for the automatic client reroute enironment when connecting to the DB2 for z/os serers Chapter 18. XA support for a Sysplex in non-jaa clients Enabling XA support for a Sysplex in non-jaa clients Chapter 19. Configuring your deelopment enironment to build and run CLI and ODBC applications. 251 Setting up the ODBC enironment (Linux and UNIX) Sample build scripts and configurations for the unixodbc drier manager Setting up the Windows CLI enironment Selecting a different DB2 copy for your Windows CLI application CLI bind files and package names Bind option limitations for CLI packages Chapter 20. Building CLI applications 261 Building CLI applications on UNIX AIX CLI application compile and link options 262 HP-UX CLI application compile and link options Linux CLI application compile and link options 263 Solaris CLI application compile and link options 264 Building CLI multi-connection applications on UNIX Building CLI applications on Windows Windows CLI application compile and link options Building CLI multi-connection applications on Windows Building CLI applications with configuration files 271 Building CLI stored procedures with configuration files Chapter 21. Building CLI routines Building CLI routines on UNIX AIX CLI routine compile and link options HP-UX CLI routine compile and link options 277 Linux CLI routine compile and link options Solaris CLI routine compile and link options 279 Building CLI routines on Windows Windows CLI routine compile and link options 281 Appendix A. Oeriew of the DB2 technical information DB2 technical library in hardcopy or PDF format 283 Displaying SQL state help from the command line processor Accessing different ersions of the DB2 Information Center Updating the DB2 Information Center installed on your computer or intranet serer Manually updating the DB2 Information Center installed on your computer or intranet serer DB2 tutorials DB2 troubleshooting information Terms and conditions Appendix B. Notices Index Contents

8 i Call Leel Interface Guide and Reference Volume 1

9 About this book The Call Leel Interface (CLI) Guide and Reference is in two olumes. Volume 1 describes how to use CLI to create database applications for DB2 for Linux, UNIX, and Windows. Volume 2 is a reference that describes CLI functions, keywords and configuration. The Call Leel Interface (CLI) Guide and Reference is in two olumes: Volume 1 describes how to use CLI to create database applications for DB2 for Linux, UNIX, and Windows. Volume 2 is a reference that describes CLI functions, keywords and configuration. Copyright IBM Corp ii

10 iii Call Leel Interface Guide and Reference Volume 1

11 Chapter 1. Introduction to DB2 Call Leel Interface and ODBC DB2 Call Leel Interface (CLI) is IBM's callable SQL interface to the DB2 family of database serers. It is a 'C' and 'C++' application programming interface for relational database access that uses function calls to pass dynamic SQL statements as function arguments. You can use the CLI interface to access the following IBM data serer databases: DB2 Version 9 for Linux, UNIX, and Windows DB2 Uniersal Database Version 8 (and later) for OS/390 and z/os DB2 for IBM i 5.4 and later IBM Informix database serer Version CLI is an alternatie to embedded dynamic SQL, but unlike embedded SQL, it does not require host ariables or a precompiler. Applications can be run against a ariety of databases without haing to be compiled against each of these databases. Applications use procedure calls at run time to connect to databases, issue SQL statements, and retriee data and status information. The CLI interface proides many features not aailable in embedded SQL. For example: CLI proides function calls that support a way of querying database catalogs that is consistent across the DB2 family. This reduces the need to write catalog queries that must be tailored to specific database serers. CLI proides the ability to scroll through a cursor: Forward by one or more rows Backward by one or more rows Forward from the first row by one or more rows Backward from the last row by one or more rows From a preiously stored location in the cursor. Stored procedures called from application programs that were written using CLI can return result sets to those programs. CLI is based on the Microsoft Open Database Connectiity (ODBC) specification, and the International Standard for SQL/CLI. These specifications were chosen as the basis for the DB2 Call Leel Interface in an effort to follow industry standards and to proide a shorter learning cure for those application programmers already familiar with either of these database interfaces. In addition, some DB2 specific extensions hae been added to help the application programmer specifically exploit DB2 features. The CLI drier also acts as an ODBC drier when loaded by an ODBC drier manager. It conforms to ODBC CLI Background information To understand CLI or any callable SQL interface, it is helpful to understand what it is based on, and to compare it with existing interfaces. Copyright IBM Corp

12 The X/Open Company and the SQL Access Group jointly deeloped a specification for a callable SQL interface referred to as the X/Open Call Leel Interface. The goal of this interface is to increase the portability of applications by enabling them to become independent of any one database endor's programming interface. Most of the X/Open Call Leel Interface specification has been accepted as part of the ISO Call Leel Interface International Standard (ISO/IEC :1995 SQL/CLI). Microsoft deeloped a callable SQL interface called Open Database Connectiity (ODBC) for Microsoft operating systems based on a preliminary draft of X/Open CLI. The ODBC specification also includes an operating enironment where database-specific ODBC driers are dynamically loaded at run time by a drier manager based on the data source (database name) proided on the connect request. The application is linked directly to a single drier manager library rather than to each DBMS's library. The drier manager mediates the application's function calls at run time and ensures they are directed to the appropriate DBMS-specific ODBC drier. Because the ODBC drier manager only knows about the ODBC-specific functions, DBMS-specific functions cannot be accessed in an ODBC enironment. DBMS-specific dynamic SQL statements are supported through a mechanism called an escape clause. ODBC is not limited to Microsoft operating systems; other implementations are aailable on arious platforms. The CLI load library can be loaded as an ODBC drier by an ODBC drier manager. For ODBC application deelopment, you must obtain an ODBC Software Deelopment Kit. For the Windows platform, the ODBC SDK is aailable as part of the Microsoft Data Access Components (MDAC) SDK, aailable for download from For non-windows platforms, the ODBC SDK is proided by other endors. When deeloping ODBC applications that may connect to DB2 serers, use the Call Leel Interface Guide and Reference Volume 1 and the Call Leel Interface Guide and Reference Volume 2 (for information about DB2 specific extensions and diagnostic information), in conjunction with the ODBC Programmer's Reference and SDK Guide aailable from Microsoft. Applications written using CLI APIs link directly to the CLI library. CLI includes support for many ODBC and ISO SQL/CLI functions, as well as DB2 specific functions. The following DB2 features are aailable to both ODBC and CLI applications: double byte (graphic) data types stored procedures Distributed Unit of Work (DUOW), two phase commit compound SQL user defined types (UDT) user defined functions (UDF) Comparison of CLI and ODBC This topic discusses the support proided by the DB2 ODBC drier, and how it differs from CLI drier. 2 Call Leel Interface Guide and Reference Volume 1

13 This topic discusses the support proided by the DB2 ODBC drier, and how it differs from CLI drier. Figure 1 compares CLI and the DB2 ODBC drier. The left side shows an ODBC drier under the ODBC Drier Manager, and the right side illustrates CLI, the callable interface designed for DB2 applications. Data Serer Client refers to all aailable IBM Data Serer Clients. DB2 serer refers to all DB2 serer products on Linux, UNIX, and Windows. ODBC Drier Manager Enironment Application DB2 CLI Enironment Application ODBC Drier Manager DB2 CLI drier other ODBC drier A DBMS A other ODBC drier B Gateway B DB2 ODBC drier Data Serer Client Data Serer Client DB2 Serer DB2 Connect DBMS B DB2 Serer DB2 Connect DB2 (MVS) SQL/DS SQL/400 Other DRDA DBMS Figure 1. CLI and ODBC. Chapter 1. CLI and ODBC 3

14 In an ODBC enironment, the Drier Manager proides the interface to the application. It also dynamically loads the necessary drier for the database serer that the application connects to. It is the drier that implements the ODBC function set, with the exception of some extended functions implemented by the Drier Manager. In this enironment CLI conforms to ODBC For ODBC application deelopment, you must obtain an ODBC Software Deelopment Kit. For the Windows platform, the ODBC SDK is aailable as part of the Microsoft Data Access Components (MDAC) SDK, aailable for download from For non-windows platforms, the ODBC SDK is proided by other endors. In enironments without an ODBC drier manager, CLI is a self sufficient drier which supports a subset of the functions proided by the ODBC drier. Table 1 summarizes the two leels of support, and the CLI and ODBC function summary proides a complete list of ODBC functions and indicates if they are supported. Table 1. CLI ODBC support ODBC features DB2 ODBC Drier CLI Core leel functions All All Leel 1 functions All All Leel 2 functions All All, except for SQLDriers() Additional CLI functions All, functions can be accessed by SQLSetConnectAttr() dynamically loading the CLI library. SQLGetEnAttr() SQLSetEnAttr() SQLSetColAttributes() SQLGetSQLCA() SQLBindFileToCol() SQLBindFileToParam() SQLExtendedBind() SQLExtendedPrepare() SQLGetLength() SQLGetPosition() SQLGetSubString() 4 Call Leel Interface Guide and Reference Volume 1

15 Table 1. CLI ODBC support (continued) ODBC features DB2 ODBC Drier CLI SQL data types All the types listed for CLI. SQL_BIGINT SQL_BINARY SQL_BIT SQL_BLOB SQL_BLOB_LOCATOR SQL_CHAR SQL_CLOB SQL_CLOB_LOCATOR SQL_DBCLOB SQL_DBCLOB_LOCATOR SQL_DECIMAL SQL_DOUBLE SQL_FLOAT SQL_GRAPHIC SQL_INTEGER SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_LONGVARGRAPHIC SQL_NUMERIC SQL_REAL SQL_SMALLINT SQL_TINYINT SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARBINARY SQL_VARCHAR SQL_VARGRAPHIC SQL_WCHAR C data types All the types listed for CLI. SQL_C_BINARY SQL_C_BIT SQL_C_BLOB_LOCATOR SQL_C_CHAR SQL_C_CLOB_LOCATOR SQL_C_TYPE_DATE SQL_C_DBCHAR SQL_C_DBCLOB_LOCATOR SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_SHORT SQL_C_TYPE_TIME SQL_C_TYPE_TIMESTAMP SQL_C_TIMESTAMP_EXT SQL_C_TINYINT SQL_C_SBIGINT SQL_C_UBIGINT SQL_C_NUMERIC 1 SQL_C_WCHAR Return codes All the codes listed for CLI. SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_NEED_DATA SQL_NO_DATA_FOUND SQL_ERROR SQL_INVALID_HANDLE Chapter 1. CLI and ODBC 5

16 Table 1. CLI ODBC support (continued) ODBC features DB2 ODBC Drier CLI SQLSTATES Mapped to X/Open SQLSTATES with additional IBM SQLSTATES, with the Mapped to X/Open SQLSTATES with additional IBM SQLSTATES exception of the ODBC type 08S01. Multiple connections per application Supported Supported Dynamic loading of drier Supported Not applicable Note: 1. Only supported on Windows operating systems. 2. The listed SQL data types are supported for compatibility with ODBC 2.0. SQL_DATE SQL_TIME SQL_TIMESTAMP You should use the SQL_TYPE_DATE, SQL_TYPE_TIME, or SQL_TYPE_TIMESTAMP instead to aoid any data type mappings. 3. The listed SQL data types and C data types are supported for compatibility with ODBC 2.0. SQL_C_DATE SQL_C_TIME SQL_C_TIMESTAMP You should use the SQL_C_TYPE_DATE, SQL_C_TYPE_TIME, or SQL_C_TYPE_TIMESTAMP instead to aoid any data type mappings. Isolation leels The table 2 maps IBM RDBMSs isolation leels to ODBC transaction isolation leels. The SQLGetInfo() function indicates which isolation leels are aailable. Table 2. Isolation leels under ODBC IBM isolation leel ODBC isolation leel Cursor stability SQL_TXN_READ_COMMITTED Repeatable read SQL_TXN_SERIALIZABLE_READ Read stability SQL_TXN_REPEATABLE_READ Uncommitted read SQL_TXN_READ_UNCOMMITTED No commit (no equialent in ODBC) Note: SQLSetConnectAttr() and SQLSetStmtAttr() will return SQL_ERROR with an SQLSTATE of HY009 if you try to set an unsupported isolation leel. Restriction Mixing ODBC and CLI features and function calls in an application is not supported on the Windows 64-bit operating system. 6 Call Leel Interface Guide and Reference Volume 1

17 Chapter 2. IBM Data Serer CLI and ODBC driers In the IBM Data Serer Client and the IBM Data Serer Runtime Client there is a drier for the CLI application programming interface (API) and the ODBC API. This drier is commonly referred to throughout the DB2 Information Center and DB2 books as the IBM Data Serer CLI drier or the IBM Data Serer CLI/ODBC drier. In the IBM Data Serer Client and the IBM Data Serer Runtime Client there is a drier for the CLI application programming interface (API) and the ODBC API. This drier is commonly referred to throughout the DB2 Information Center and DB2 books as the IBM Data Serer CLI drier or the IBM Data Serer CLI/ODBC drier. New with DB2 Version 9, there is also a separate CLI and ODBC drier called the IBM Data Serer Drier for ODBC and CLI. The IBM Data Serer Drier for ODBC and CLI proides runtime support for the CLI and ODBC APIs. Howeer, this drier is installed and configured separately, and supports a subset of the functionality of the DB2 clients, such as connectiity, in addition to the CLI and ODBC API support. Information that applies to the CLI and ODBC drier that is part of the DB2 client generally applies to the IBM Data Serer Drier for ODBC and CLI too. Howeer, there are some restrictions and some functionality that is unique to the IBM Data Serer Drier for ODBC and CLI. Information that applies only to the IBM Data Serer Drier for ODBC and CLI will use the full title of the drier to distinguish it from general information that applies to the ODBC and CLI drier that comes with the DB2 clients. For more information about the IBM Data Serer Drier for ODBC and CLI, see: IBM Data Serer Drier for ODBC and CLI oeriew. IBM Data Serer Drier for ODBC and CLI oeriew The IBM Data Serer Drier for ODBC and CLI proides runtime support for the CLI application programming interface (API) and the ODBC API. Though the IBM Data Serer Client and IBM Data Serer Runtime Client both support the CLI and ODBC APIs, this drier is not a part of either IBM Data Serer Client or IBM Data Serer Runtime Client. It is aailable separately, installed separately, and supports a subset of the functionality of the IBM Data Serer Client. The IBM Data Serer Drier for ODBC and CLI proides runtime support for the CLI application programming interface (API) and the ODBC API. Though the IBM Data Serer Client and IBM Data Serer Runtime Client both support the CLI and ODBC APIs, this drier is not a part of either IBM Data Serer Client or IBM Data Serer Runtime Client. It is aailable separately, installed separately, and supports a subset of the functionality of the IBM Data Serer Client. Adantages of the IBM Data Serer Drier for ODBC and CLI The drier has a much smaller footprint than the IBM Data Serer Client and the IBM Data Serer Runtime Client. You can hae multiple installations of the drier on a single machine. Copyright IBM Corp

18 You can install the drier on a machine that already has an IBM Data Serer Client installed. You can include the drier in your database application installation package, and redistribute the drier with your applications. Under certain conditions, you can redistribute the drier with your database applications royalty-free. The drier can reside on an NFS mounted file system. Functionality of the IBM Data Serer Drier for ODBC and CLI The IBM Data Serer Drier for ODBC and CLI proides: runtime support for the CLI API; runtime support for the ODBC API; runtime support for the XA API; database connectiity; support for DB2 Interactie Call Leel Interface (db2cli); LDAP Database Directory support; and tracing, logging, and diagnostic support. See: Restrictions of the IBM Data Serer Drier for ODBC and CLI on page 37. Obtaining the IBM Data Serer Drier for ODBC and CLI The IBM Data Serer Drier for ODBC and CLI is not part of the IBM Data Serer Client or the IBM Data Serer Runtime Client. It is aailable to download from the internet, and it is on the DB2 Version 9 install CD. Procedure You can obtain the IBM Data Serer Drier for ODBC and CLI from following sources: Go to the IBM Support Fix Central website: fixcentral/. Data Serer client and drier packages are found under the Information Management Product Group and IBM Data Serer Client Packages Product selection. Select the appropriate Installed Version and Platform and click Continue. Click Continue again on the next screen and you will be presented with a list of all client and drier packages aailable for your platform, including IBM Data Serer Drier for ODBC and CLI. or Copy the drier from the DB2 install CD. The drier is in a compressed file called "ibm_data_serer_drier_for_odbc_cli.zip" on Windows operating systems, and "ibm_data_serer_drier_for_odbc_cli.tar.z" on other operating systems. Installing the IBM Data Serer Drier for ODBC and CLI The IBM Data Serer Drier for ODBC and CLI is not part of the IBM Data Serer Client or the IBM Data Serer Runtime Clientt. It must be installed separately. Before you begin To install the IBM Data Serer Drier for ODBC and CLI, you need to obtain the compressed file that contains the drier. See Obtaining the IBM Data Serer Drier for ODBC and CLI. 8 Call Leel Interface Guide and Reference Volume 1

19 About this task There is no installation program for the IBM Data Serer Drier for ODBC and CLI. You must install the drier manually. Procedure 1. Copy the compressed file that contains the drier onto the target machine from the internet or a DB2 Version 9 installation CD. 2. Uncompress that file into your chosen install directory on the target machine. 3. Optional: Remoe the compressed file. Example If you are installing the IBM Data Serer Drier for ODBC and CLI under the following conditions: the operating systems on the target machine is AIX ; and the DB2 Version 9 CD is mounted on the target machine. the steps you would follow are: 1. Create the directory $HOME/db2_cli_odbc_drier, where you will install the drier. 2. Locate the compressed file ibm_data_serer_drier_for_odbc_cli.tar.z on the install CD. 3. Copy ibm_data_serer_drier_for_odbc_cli.tar.z to the install directory, $HOME/db2_cli_odbc_drier. 4. Uncompress ibm_data_serer_drier_for_odbc_cli.tar.z: cd $HOME/db2_cli_odbc_drier uncompress ibm_data_serer_drier_for_odbc_cli.tar.z tar -xf ibm_data_serer_drier_for_odbc_cli.tar 5. Delete ibm_data_serer_drier_for_odbc_cli.tar.z. 6. Ensure that the following requirements are met if you installed the drier on a NFS file system: On UNIX or Linux operating systems the db2dump and the db2 directory need to be writable. Alternatiely, the path you hae referenced in the diagpath parameter must be writable. If host or i5/os data serers are being accessed directly ensure the license directory is writable. Installing multiple copies of the IBM Data Serer Drier for ODBC and CLI on the same machine The IBM Data Serer Drier for ODBC and CLI is not part of the IBM data serer client or the IBM Data Serer Runtime Client. It must be installed separately. You can install multiple copies of the IBM Data Serer Drier for ODBC and CLI on the same machine. You might want to do this if you hae two database applications on the same machine that require different ersions of the drier. Before you begin To install multiple copies of the IBM Data Serer Drier for ODBC and CLI on the same machine, you need to obtain the compressed file that contains the drier. See: Chapter 2. IBM Data Serer CLI and ODBC driers 9

20 Obtaining the IBM Data Serer Drier for ODBC and CLI on page 8. Procedure For each copy of the IBM Data Serer Drier for ODBC and CLI that you are installing: 1. Create a unique target installation directory. 2. Follow the installation steps outlined in Installing the IBM Data Serer Drier for ODBC and CLI on page Ensure the application is using the correct copy of the drier. Aoid relying on the LD_LIBRARY_PATH enironment ariable as this can lead to inadertent loading of the incorrect drier. Dynamically load the drier explicitly from the target installation directory. Example If you are installing two copies of the IBM Data Serer Drier for ODBC and CLI under the following conditions: the operating systems on the target machine is AIX; and the DB2 Version 9 CD is mounted on the target machine. the steps you would follow are: 1. Create the two directories, $HOME/db2_cli_odbc_drier1 and $HOME/db2_cli_odbc_drier2, where you will install the drier. 2. Locate the compressed file that contains the drier on the install CD. In this scenario, the file would be called ibm_data_serer_drier_for_odbc_cli.tar.z. 3. Copy ibm_data_serer_drier_for_odbc_cli.tar.z to the install directories, $HOME/db2_cli_odbc_drier1 and $HOME/db2_cli_odbc_drier2. 4. Uncompress ibm_data_serer_drier_for_odbc_cli.tar.z in each directory: cd $HOME/db2_cli_odbc_drier1 uncompress ibm_data_serer_drier_for_odbc_cli.tar.z tar -xf ibm_data_serer_drier_for_odbc_cli.tar cd $HOME/db2_cli_odbc_drier2 uncompress ibm_data_serer_drier_for_odbc_cli.tar.z tar -xf ibm_data_serer_drier_for_odbc_cli.tar 5. Delete ibm_data_serer_drier_for_odbc_cli.tar.z. Installing the IBM Data Serer Drier for ODBC and CLI on a machine with an existing DB2 client The IBM Data Serer Drier for ODBC and CLI is not part of the IBM Data Serer Client or the IBM Data Serer Runtime Client. It must be installed separately. You can install one or more copies of the IBM Data Serer Drier for ODBC and CLI on a machine where an IBM Data Serer Client or IBM Data Serer Runtime Client is already installed. You might want to do this if you hae deeloped some ODBC or CLI database applications with the IBM Data Serer Client that you plan to deploy with the IBM Data Serer Drier for ODBC and CLI, because it enables you to test the database applications with the drier on the same machine as your deelopment enironment. 10 Call Leel Interface Guide and Reference Volume 1

21 Before you begin To install the IBM Data Serer Drier for ODBC and CLI on the same machine as an IBM Data Serer Client or IBM Data Serer Runtime Client, you need: to obtain the compressed file that contains the drier. See: Obtaining the IBM Data Serer Drier for ODBC and CLI on page 8. About this task The procedure for installing one or more copies of the IBM Data Serer Drier for ODBC and CLI on a machine that already has an IBM Data Serer Client or IBM Data Serer Runtime Client installed is the same as the procedure for installing the drier on a machine that has no IBM Data Serer Client installed. Procedure See: Installing the IBM Data Serer Drier for ODBC and CLI on page 8 and Installing multiple copies of the IBM Data Serer Drier for ODBC and CLI on the same machine on page 9. What to do next Ensure the application is using the correct copy of the drier. Aoid relying on the LD_LIBRARY_PATH enironment ariable as this can lead to inadertent loading of the incorrect drier. Dynamically load the drier explicitly from the target installation directory. Configuring the IBM Data Serer Drier for ODBC and CLI The IBM Data Serer Drier for ODBC and CLI is not part of the IBM Data Serer Client or the IBM Data Serer Runtime Client. It must be installed and configured separately. You must configure the IBM Data Serer Drier for ODBC and CLI, and the software components of your database application runtime enironment in order for your applications to use the drier successfully. Before you begin To configure the IBM Data Serer Drier for ODBC and CLI and your application enironment for the drier, you need: one or more copies of the drier installed. See Installing the IBM Data Serer Drier for ODBC and CLI on page 8. Procedure To configure theibm Data Serer Drier for ODBC and CLI, and the runtime enironment of your IBM Data Serer Drier for ODBC and CLI applications to use the drier: 1. Configure aspects of the drier's behaior such as data source name, user name, performance options, and connection options by updating the db2cli.ini initialization file. The location of thedb2cli.ini file might change based on whether the Microsoft ODBC Drier Manager is used, the type of data source names (DSN) used, the type of client or drier being installed, and whether the registry ariable DB2CLIINIPATH is set. See db2cli.ini initialization file on page 12. Chapter 2. IBM Data Serer CLI and ODBC driers 11

22 There is no support for the Command Line Processor (CLP) with the IBM Data Serer Drier for ODBC and CLI. For this reason, you can not update CLI configuration using the CLP command "db2 update CLI cfg"; you must update the db2cli.ini initialization file manually. If you hae multiple copies of the IBM Data Serer Drier for ODBC and CLI installed, each copy of the drier will hae its own db2cli.ini file. Ensure you make the additions to the db2cli.ini for the correct copy of the drier. 2. Configure application enironment ariables. See Configuring enironment ariables for the IBM Data Serer Drier for ODBC and CLI on page For applications participating in transactions managed by the Microsoft Distributed Transaction Coordinator (DTC) only, you must register the drier with the DTC. See Registering the IBM Data Serer Drier for ODBC and CLI with the Microsoft DTC on page For ODBC applications using the Microsoft ODBC drier manager only, you must register the drier with the Microsoft drier manager. See Registering the IBM Data Serer Drier for ODBC and CLI with the Microsoft ODBC drier manager on page 19. db2cli.ini initialization file The CLI/ODBC initialization file (db2cli.ini) contains arious keywords and alues that can be used to configure the behaior of CLI and the applications using it. The keywords are associated with the database alias name, and affect all CLI and ODBC applications that access the database. The db2cli.ini.sample sample configuration file is included to help you get started. You can create a db2cli.ini file that is based on the db2cli.ini.sample file and that is stored in the same location. The location of the sample configuration file depends on your drier type and platform. For IBM Data Serer Client, IBM Data Serer Runtime Client, or IBM Data Serer Drier Package, the sample configuration file is created in one of the following paths: On AIX, HP-UX, Linux, or Solaris operating systems: installation_path/cfg On Windows XP and Windows Serer 2003: C:\Documents and Settings\All Users\Application Data\IBM\DB2\drier_copy_name\cfg On Windows Vista and Windows Serer 2008: C:\ProgramData\IBM\DB2\ drier_copy_name\cfg For example, if you use IBM Data Serer Drier Package for Windows XP, and the data serer drier copy name is IBMDBCL1, then the db2cli.ini.sample file is created in the C:\Documents and Settings\All Users\Application Data\IBM\DB2\IBMDBCL1\cfg directory. For IBM Data Serer Drier for ODBC and CLI, the sample configuration file is created in one of the following paths: On AIX, HP-UX, Linux, or Solaris operating systems: installation_path/cfg On Windows : installation_path\cfg where installation_path is the file path where drier files are extracted. 12 Call Leel Interface Guide and Reference Volume 1

23 For example, if you use IBM Data Serer Drier for ODBC and CLI for Windows Vista, and the drier is installed in the C:\IBMDB2\CLIDRIVER\V97FP3 directory, then the db2cli.ini.sample file is created in the C:\IBMDB2\CLIDRIVER\V97FP3\cfg directory. When the ODBC Drier Manager is used to configure a user DSN on Windows operating systems, the db2cli.ini file is created in Documents and Settings\User Name where User Name represents the name of the user directory. You can use the enironment ariable DB2CLIINIPATH to specify a different location for the db2cli.ini file. The configuration keywords enable you to: Configure general features such as data source name, user name, and password. Set options that will affect performance. Indicate query parameters such as wild card characters. Set patches or work-arounds for arious ODBC applications. Set other, more specific features associated with the connection, such as code pages and IBM GRAPHIC data types. Oerride default connection options specified by an application. For example, if an application requests Unicode support from the CLI drier by setting the SQL_ATTR_ANSI_APP connection attribute, then setting DisableUnicode=1 in the db2cli.ini file will force the CLI drier not to proide the application with Unicode support. Note: If the CLI/ODBC configuration keywords set in the db2cli.ini file conflict with keywords in the SQLDrierConnect() connection string, then the SQLDrierConnect() keywords will take precedence. The db2cli.ini initialization file is an ASCII file which stores alues for the CLI configuration options. A sample file is included to help you get started. While most CLI/ODBC configuration keywords are set in the db2cli.ini initialization file, some keywords are set by proiding the keyword information in the connection string to SQLDrierConnect() instead. There is one section within the file for each database (data source) the user wishes to configure. If needed, there is also a common section that affects all database connections. Only the keywords that apply to all database connections through the CLI/ODBC drier are included in the COMMON section. This includes the following keywords: CheckForFork DiagPath DisableMultiThread JDBCTrace JDBCTraceFlush JDBCTracePathName QueryTimeoutInteral ReadCommonSectionOnNullConnect Trace TraceComm Chapter 2. IBM Data Serer CLI and ODBC driers 13

24 TraceErrImmediate TraceFileName TraceFlush TraceFlushOnError TraceLocks TracePathName TracePIDList TracePIDTID TraceRefreshInteral TraceStmtOnly TraceTime TraceTimeStamp All other keywords are to be placed in the database specific section. Note: Configuration keywords are alid in the COMMON section, howeer, they will apply to all database connections. The COMMON section of the db2cli.ini file begins with: [COMMON] Before setting a common keyword it is important to ealuate its affect on all CLI/ODBC connections from that client. A keyword such as TRACE, for example, will generate information about all CLI/ODBC applications connecting to DB2 on that client, een if you are intending to troubleshoot only one of those applications. Each database specific section always begins with the name of the data source name (DSN) between square brackets: [data source name] This is called the section header. The parameters are set by specifying a keyword with its associated keyword alue in the form: KeywordName =keywordvalue All the keywords and their associated alues for each database must be located under the database section header. If the database-specific section does not contain a DBAlias keyword, the data source name is used as the database alias when the connection is established. The keyword settings in each section apply only to the applicable database alias. The keywords are not case sensitie; howeer, their alues can be if the alues are character based. If a database is not found in the.ini file, the default alues for these keywords are in effect. Comment lines are introduced by haing a semicolon in the first position of a new line. Blank lines are permitted. If duplicate entries for a keyword exist, the first entry is used (and no warning is gien). The following sample.ini file contains two database alias sections: 14 Call Leel Interface Guide and Reference Volume 1

25 ; This is a comment line. [MYDB22] AutoCommit=0 TableType=" TABLE, SYSTEM TABLE " ; This is another comment line. [MYDB2MVS] CurrentSQLID=SAAID TableType=" TABLE " SchemaList=" USER1,CURRENT SQLID, USER2 " Although you can edit the db2cli.ini file manually on all platforms, it is recommended that you use the UPDATE CLI CONFIGURATION command if it is aailable. You must add a blank line after the last entry if you manually edit the db2cli.ini file. Configuring enironment ariables for the IBM Data Serer Drier for ODBC and CLI The IBM Data Serer Drier for ODBC and CLI is not part of the IBM Data Serer Client or the IBM Data Serer Runtime Client. It must be installed and configured separately. To use the IBM Data Serer Drier for ODBC and CLI, there are two types of enironment ariables that you might hae to set: enironment ariables that hae replaced some DB2 registry ariables; and an enironment ariable that tells your applications where to find the drier libraries. Before you begin To configure enironment ariables for the IBM Data Serer Drier for ODBC and CLI, you need one or more copies of the drier installed. See Installing the IBM Data Serer Drier for ODBC and CLI on page 8. Restrictions If there are multiple ersions of the IBM Data Serer Drier for ODBC and CLI installed on the same machine, or if there are other DB2 Version 9 products installed on the same machine, setting enironment ariables (for example, setting LIBPATH or LD_LIBRARY_PATH to point to the IBM Data Serer Drier for ODBC and CLI library) might break existing applications. When setting an enironment ariable, ensure that it is appropriate for all applications running in the scope of that enironment. IBM Data Serer Drier for ODBC and CLI on 64 bit UNIX and Linux systems also packages 32 bit drier library to support 32 bit CLI applications. On UNIX and Linux systems, you can associate either 32 bit or 64 bit libraries with an instance, not both. You can set LIBPATH or LD_LIBRARY_PATH to either lib32 or lib64 library directories of IBM Data Serer Drier for ODBC and CLI. You can also access lib64 library using a preset soft link from the lib directory. The IBM Data Serer Drier for ODBC and CLI on Windows systems contains both 32 bit and 64 bit necessary runtime DLLs in the same bin directory. Procedure To configure enironment ariables for the IBM Data Serer Drier for ODBC and CLI: Chapter 2. IBM Data Serer CLI and ODBC driers 15

26 1. Optional: Set any applicable DB2 enironment ariables corresponding to its equialent DB2 registry ariables. There is no support for the command line processor (CLP) with the IBM Data Serer Drier for ODBC and CLI. For this reason, you cannot configure DB2 registry ariables using the db2set CLP command. Required DB2 registry ariables hae been replaced with enironment ariables. For a list of the enironment ariables that can be used instead of DB2 registry ariables, see: Enironment ariables supported by the IBM Data Serer Drier for ODBC and CLI. 2. Optional: You can set the local enironment ariable DB2_CLI_DRIVER_INSTALL_PATH to the directory in which the drier is installed. If there are multiple copies of the IBM Data Serer Drier for ODBC and CLI installed, ensure that the DB2_CLI_DRIVER_INSTALL_PATH points to the intended copy of the drier. Setting the DB2_CLI_DRIVER_INSTALL_PATH ariable forces IBM Data Serer Drier for ODBC and CLI to use the directory specified with the DB2_CLI_DRIVER_INSTALL_PATH ariable as the install location of the drier. For example: export DB2_CLI_DRIVER_INSTALL_PATH=/home/db2inst1/db2clidrier/clidrier where /home/db2inst1/db2clidrier is the install path where the CLI drier is installed 3. Optional: Set the enironment ariable LIBPATH (on AIX operating systems), SHLIB_PATH (on HP-UX systems), or LD_LIBRARY_PATH (on rest of the UNIX and Linux systems) to the lib directory in which the drier is installed. For example (on AIX systems): export LIBPATH=/home/db2inst1/db2clidrier/clidrier/lib If there are multiple copies of the IBM Data Serer Drier for ODBC and CLI installed, ensure LIBPATH or LD_LIBRARY_PATH points to the intended copy of the drier. Do not set LIBPATH or LD_LIBRARY_PATH ariables to multiple copies of the IBM Data Serer Drier for ODBC and CLI that are installed on your system. Do not set LIBPATH or LD_LIBRARY_PATH ariables to both lib32 and lib64 (or lib) library directories. This step is not necessary if your applications statically link to, or dynamically load the drier library (db2cli.dll on Windows systems, or libdb2.a on other systems) with the fully qualified name. You must dynamically load the library using the fully qualified library name. On Windows operating systems, you must use the LoadLibraryEx method specifying the LOAD_WITH_ALTERED_SEARCH_PATH parameter and the path to the drier DLL. 4. Optional: Set the PATH enironment ariable to include the bin directory of the drier installation in all systems if you require the use of utilities like db2leel, db2cli, and db2trc. In UNIX and Linux systems, add adm directory of the drier installation to the PATH enironment ariable in addition to the bin directory. For Example (on all UNIX and Linux systems) : export PATH=/home/db2inst1/db2clidrier/clidrier/bin:/home/db2inst1/db2clidrier/clidrier/adm:$PATH Enironment ariables supported by the IBM Data Serer Drier for ODBC and CLI: The IBM Data Serer Drier for ODBC and CLI does not support the command line processor (CLP). This means that the usual mechanism to set DB2 registry 16 Call Leel Interface Guide and Reference Volume 1

27 ariables, using the db2set CLP command, is not possible. Releant DB2 registry ariables will be supported with the IBM Data Serer Drier for ODBC and CLI as enironment ariables instead. IBM Data Serer Drier for ODBC and CLI is not part of the IBM Data Serer Client or the IBM Data Serer Runtime Client. It must be installed and configured separately. The IBM Data Serer Drier for ODBC and CLI does not support the command line processor (CLP). This means that the usual mechanism to set DB2 registry ariables, using the db2set CLP command, is not possible. Releant DB2 registry ariables will be supported with the IBM Data Serer Drier for ODBC and CLI as enironment ariables instead. The DB2 registry ariables that will be supported by the IBM Data Serer Drier for ODBC and CLI as enironment ariables are: Table 3. DB2 registry ariables supported as enironment ariables Type of ariable Variable name(s) General ariables DB2ACCOUNT DB2BIDI DB2CODEPAGE DB2GRAPHICUNICODESERVER DB2LOCALE DB2TERRITORY System enironment ariables DB2DOMAINLIST Communications ariables DB2_FORCE_NLS_CACHE DB2SORCVBUF DB2SOSNDBUF DB2TCP_CLIENT_RCVTIMEOUT Performance ariables DB2_NO_FORK_CHECK Miscellaneous ariables DB2CLIINIPATH DB2DSDRIVER_CFG_PATH DB2DSDRIVER_CLIENT_HOSTNAME DB2_ENABLE_LDAP DB2LDAP_BASEDN DB2LDAP_CLIENT_PROVIDER DB2LDAPHOST DB2LDAP_KEEP_CONNECTION DB2LDAP_SEARCH_SCOPE DB2NOEXITLIST Diagnostic ariables DB2_DIAGPATH Connection ariables AUTHENTICATION PROTOCOL PWDPLUGIN KRBPLUGIN ALTHOSTNAME ALTPORT INSTANCE BIDI Chapter 2. IBM Data Serer CLI and ODBC driers 17