® ® IBM DB2 Universal Database Call Level Interface Guide and Reference Ve r s i o n 7 SC09-2950-00 ® ® IBM DB2 Universal Database Call Level Interface Guide and Reference Ve r s i o n 7 SC09-2950-00 Before using this information and the product it supports, be sure to read the general information under “Appendix M. Notices” on page 849. This document contains proprietary information of IBM. It is provided 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 provided in this manual should not be interpreted as such. Order publications through your IBM representative or the IBM branch office serving your locality or by calling 1-800-879-2755 in the United States or 1-800-IBM-4YOU in Canada. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright International Business Machines Corporation 1993, 2000. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents About This Book ..........ix Deciding on Which Cursor Type to Use . 67 Who Should Use this book .......ix Specifying the Rowset Returned from the How this Book is Structured.......ix Result Set ............68 Typical Scrollable Cursors Application . 72 Chapter 1. Introduction to CLI......1 Using Bookmarks with Scrollable Cursors 75 DB2 CLI Background Information .....1 Sending/Retrieving Long Data in Pieces . 77 Differences Between DB2 CLI and Embedded Specifying Parameter Values at Execute SQL...............3 Time.............77 Comparing Embedded SQL and DB2 CLI . 3 Fetching Data in Pieces .......78 Advantages of Using DB2 CLI .....4 Piecewise Input and Retrieval Example . 79 Deciding on Embedded SQL or DB2 CLI . 6 Using Arrays to Input Parameter Values . 79 Supported Environments ........7 Column-Wise Array Insert ......80 Other Information Sources .......8 Row-Wise Array Insert .......81 Retrieving Diagnostic Information....83 Chapter 2. Writing a DB2 CLI Application . 9 Parameter Binding Offsets ......84 Initialization and Termination ......10 Array Input Example ........85 Handles ............11 Retrieving a Result Set into an Array....87 Connecting to One or More Data Sources 12 Returning Array Data for Column-Wise Initialization and Connection Example . 13 Bound Data ...........88 Transaction Processing .......15 Returning Array Data for Row-Wise Bound Diagnostics ...........25 Data.............89 Data Types and Data Conversion ....28 Column Binding Offsets .......90 Working with String Arguments ....36 Column-Wise, Row-Wise Binding Example 91 Querying Environment and Data Source Using Descriptors ..........91 Information ...........38 Descriptor Types .........92 Values Stored in a Descriptor .....93 Chapter 3. Using Advanced Features . 39 Allocating and Freeing Descriptors . 95 Environment, Connection, and Statement Getting, Setting, and Copying Descriptor Attributes .............40 Fields .............98 Writing Multi-Threaded Applications . 44 Descriptor Sample ........101 When to Use Multiple Threads.....44 Using Compound SQL ........103 Programming Tips .........45 ATOMIC and NOT ATOMIC Compound Multisite Updates (Two Phase Commit) . 48 SQL.............104 DB2 as Transaction Monitor ......48 Compound SQL Error Handling ....106 Microsoft Transaction Server (MTS) as Compound SQL Example ......107 Transaction Monitor ........54 Using Large Objects .........108 Process-based XA-Compliant Transaction LOB Examples ..........112 Program Monitor (XA TP) ......61 Using LOBs in ODBC Applications . 113 Host and AS/400 Database Servers . 62 Using User Defined Types (UDT) ....114 Querying System Catalog Information . 62 User Defined Type Example .....114 Input Arguments on Catalog Functions . 63 Using Stored Procedures .......116 Catalog Functions Example ......64 Calling Stored Procedures ......117 Scrollable Cursors ..........65 Registering Stored Procedures.....119 Static, Read-Only Cursor .......66 Handling Stored Procedure Arguments Keyset-Driven Cursor ........66 (SQLDA)............119 © Copyright IBM Corp. 1993, 2000 iii Returning Result Sets from Stored SQLBrowseConnect - Get Required Procedures ...........120 Attributes to Connect to Data source . 258 Writing a Stored Procedure in CLI . 122 SQLBuildDataLink - Build DATALINK Stored Procedure Example ......122 Value .............264 Mixing Embedded SQL and DB2 CLI . 127 SQLBulkOperations - Add, Update, Mixed Embedded SQL and DB2 CLI Delete or Fetch a Set of Rows .....268 Example ............128 SQLCancel - Cancel Statement ....282 Asynchronous Execution of CLI .....129 SQLCloseCursor - Close Cursor and Typical Asynchronous Application . 130 Discard Pending Results ......285 Sample Asynchronous Application . 133 SQLColAttribute - Return a Column Using Vendor Escape Clauses ......135 Attribute............288 Escape Clause Syntax .......135 SQLColAttributes - Get Column ODBC Date, Time, Timestamp Data . 136 Attributes ...........301 ODBC Outer Join Syntax ......136 SQLColumnPrivileges - Get Privileges LIKE Predicate Escape Clauses ....136 Associated With The Columns of A Table . 302 Stored Procedure Call Syntax .....137 SQLColumns - Get Column Information ODBC Scalar Functions .......137 for a Table ...........307 SQLConnect - Connect to a Data Source 314 Chapter 4. Configuring CLI/ODBC and SQLCopyDesc - Copy Descriptor Running Sample Applications .....139 Information Between Handles.....318 Setting up the DB2 CLI Runtime SQLDataSources - Get List of Data Environment ...........139 Sources ............322 Running CLI/ODBC Programs .....140 SQLDescribeCol - Return a Set of Platform Specific Details for CLI/ODBC Attributes for a Column ......326 Access ............141 SQLDescribeParam - Return Description Detailed Configuration Information . 147 of a Parameter Marker .......331 Application Development Environments . 152 SQLDisconnect - Disconnect from a Data Compiling a Sample Application....153 Source ............335 Compile and Link Options......153 SQLDriverConnect - (Expanded) Connect DB2 CLI/ODBC Configuration Keyword to a Data Source .........338 Listing .............154 SQLEndTran - End Transactions of a Configuration Keywords ......154 Connection ...........343 SQLError - Retrieve Error Information 347 Chapter 5. DB2 CLI Functions .....205 SQLExecDirect - Execute a Statement DB2 CLI Function Summary ......207 Directly ............352 SQLAllocConnect - Allocate Connection SQLExecute - Execute a Statement . 360 Handle ............214 SQLExtendedBind - Bind an Array of SQLAllocEnv - Allocate Environment Columns ............364 Handle ............215 SQLExtendedFetch - Extended Fetch SQLAllocHandle - Allocate Handle . 216 (Fetch Array of Rows) .......368 SQLAllocStmt - Allocate a Statement SQLExtendedPrepare - Prepare a Handle ............222 Statement and Set Statement Attributes . 376 SQLBindCol - Bind a Column to an SQLFetch - Fetch Next Row .....382 Application Variable or LOB Locator . 223 SQLFetchScroll - Fetch Rowset and SQLBindFileToCol - Bind LOB File Return Data for All Bound Columns . 392 Reference to LOB Column ......233 SQLForeignKeys - Get the List of Foreign SQLBindFileToParam - Bind LOB File Key Columns ..........404 Reference to LOB Parameter .....237 SQLFreeConnect - Free Connection SQLBindParameter - Bind A Parameter Handle ............409 Marker to a Buffer or LOB Locator . 241 SQLFreeEnv - Free Environment Handle 411 iv CLI Guide and Reference SQLFreeHandle - Free Handle Resources 413 SQLPrimaryKeys - Get Primary Key SQLFreeStmt - Free (or Reset) a Statement Columns of A Table ........560 Handle ............417 SQLProcedureColumns - Get SQLGetConnectAttr - Get Current Input/Output Parameter Information for Attribute Setting .........421 A Procedure ..........564 SQLGetConnectOption - Return Current SQLProcedures - Get List of Procedure Setting of A Connect Option .....424 Names............572 SQLGetCursorName - Get Cursor Name 425 SQLPutData - Passing Data Value for A SQLGetData - Get Data From a Column 428 Parameter ...........578 SQLGetDataLinkAttr - Get DataLink SQLRowCount - Get Row Count....583 Attribute Value .........436 SQLSetColAttributes - Set Column SQLGetDescField - Get Single Field Attributes ...........585 Settings of Descriptor Record .....439 SQLSetConnectAttr - Set Connection SQLGetDescRec - Get Multiple Field Attributes ...........586 Settings of Descriptor Record .....445 SQLSetConnection - Set Connection SQLGetDiagField - Get a Field of Handle ............610 Diagnostic Data .........450 SQLSetConnectOption - Set Connection SQLGetDiagRec - Get Multiple Fields Option ............612 Settings of Diagnostic Record .....459 SQLSetCursorName - Set Cursor Name 613 SQLGetEnvAttr - Retrieve Current SQLSetDescField - Set a Single Field of a Environment Attribute Value .....463 Descriptor Record.........616 SQLGetFunctions - Get Functions . 465 SQLSetDescRec - Set Multiple Descriptor SQLGetInfo - Get General Information 468 Fields for a Column or Parameter Data . 643 SQLGetLength - Retrieve Length of A SQLSetEnvAttr - Set Environment String Value...........507 Attribute............648 SQLGetPosition - Return Starting Position SQLSetParam - Bind A Parameter Marker of String ............510 to a Buffer or LOB Locator......656 SQLGetSQLCA - Get SQLCA Data SQLSetPos - Set the Cursor Position in a Structure............514 Rowset............657