DB2 for OS/390 IBM Version 5 Call Level Interface Guide and Reference SC26-8959-03 Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page vii. First Edition (June 1997) This edition applies to Version 5 of IBM DATABASE 2 Server for OS/390 (DB2 for OS/390), 5655-DB2, and to any subsequent releases until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product. This softcopy version is based on the printed edition of the book and includes the changes indicated in the printed version by vertical bars. Additional changes made to this softcopy version of the manual since the hardcopy manual was published are indicated by the hash (#) symbol in the left-hand margin. Copyright International Business Machines Corporation 1997.All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Notices . vii Programming Interface Information ........................... vii Trademarks . viii Chapter 1. Introduction to this Book and the DB2 Library ........... 1 About This Book ...................................... 1 Who Should Use This Book ............................... 1 How this Book is Structured ............................... 1 How to Read the Syntax Diagrams ........................... 2 How to Use the DB2 Library ............................... 3 How to Obtain DB2 Information ............................. 5 Summary of Changes to DB2 for OS/390 Version 5 ................. 7 Summary of Changes to This Book .......................... 14 Chapter 2. Introduction to CLI ............................ 15 DB2 CLI Background Information ........................... 15 Differences Between DB2 CLI and Embedded SQL ................ 17 Advantages of Using DB2 CLI ............................. 20 Deciding Which Interface To Use ........................... 20 Other Information Sources ............................... 21 Chapter 3. Writing a DB2 CLI Application .................... 23 Initialization and Termination .............................. 24 Transaction Processing . 29 Diagnostics . 35 Data Types and Data Conversion ........................... 37 Working With String Arguments ............................ 43 Querying Environment and Data Source Information ................ 45 Chapter 4. Configuring CLI and Running Sample Applications ....... 49 Installing DB2 CLI .................................... 49 DB2 CLI Runtime Environment ............................ 50 Setting up DB2 CLI Runtime Environment ...................... 51 Preparing a DB2 CLI Application ........................... 54 DB2 CLI Initialization File ............................... 60 Chapter 5. Functions ................................. 71 DB2 CLI Function Summary .............................. 72 SQLAllocConnect - Allocate Connection Handle .................. 76 SQLAllocEnv - Allocate Environment Handle .................... 80 SQLAllocStmt - Allocate a Statement Handle .................... 82 SQLBindCol - Bind a Column to an Application Variable ............. 84 SQLBindParameter - Binds A Parameter Marker to a Buffer ........... 89 SQLCancel - Cancel Statement ............................ 100 SQLColAttributes - Get Column Attributes ...................... 102 SQLColumnPrivileges - Get Privileges Associated With The Columns of A Table . 108 SQLColumns - Get Column Information for a Table ................ 113 SQLConnect - Connect to a Data Source ...................... 118 SQLDataSources - Get List of Data Sources .................... 124 Copyright IBM Corp. 1997 iii SQLDescribeCol - Describe Column Attributes ................... 127 SQLDescribeParam - Describe parameter marker ................. 132 SQLDisconnect - Disconnect from a Data Source ................. 134 SQLDriverConnect - (Expanded) Connect to a Data Source ........... 136 SQLError - Retrieve Error Information ........................ 142 SQLExecDirect - Execute a Statement Directly ................... 148 SQLExecute - Execute a Statement ......................... 153 SQLExtendedFetch - Extended Fetch (Fetch Array of Rows) ........... 156 SQLFetch - Fetch Next Row .............................. 163 SQLForeignKeys - Get the List of Foreign Key Columns ............. 168 SQLFreeConnect - Free Connection Handle .................... 177 SQLFreeEnv - Free Environment Handle ...................... 179 SQLFreeStmt - Free (or Reset) a Statement Handle ................ 181 SQLGetConnectOption - Returns Current Setting of A Connect Option ..... 184 SQLGetCursorName - Get Cursor Name ...................... 186 SQLGetData - Get Data From a Column ....................... 192 SQLGetEnvAttr - Returns Current Setting of An Environment Attribute ..... 205 SQLGetFunctions - Get Functions .......................... 207 SQLGetInfo - Get General Information ........................ 212 SQLGetSQLCA - Get SQLCA Data Structure .................... 228 SQLGetStmtOption - Returns Current Setting of A Statement Option ...... 235 SQLGetTypeInfo - Get Data Type Information ................... 237 SQLMoreResults - Determine If There Are More Result Sets ........... 245 SQLNativeSql - Get Native SQL Text ........................ 249 SQLNumParams - Get Number of Parameters in A SQL Statement ....... 252 SQLNumResultCols - Get Number of Result Columns ............... 254 SQLParamData - Get Next Parameter For Which A Data Value Is Needed .. 256 SQLParamOptions - Specify an Input Array for a Parameter ........... 258 SQLPrepare - Prepare a Statement ......................... 260 SQLPrimaryKeys - Get Primary Key Columns of A Table ............. 268 SQLProcedureColumns - Get Input/Output Parameter Information for A Procedure . 273 SQLProcedures - Get List of Procedure Names .................. 282 SQLPutData - Passing Data Value for A Parameter ................ 286 SQLRowCount - Get Row Count ........................... 289 SQLSetColAttributes - Set Column Attributes .................... 291 SQLSetConnection - Set Connection Handle .................... 295 SQLSetConnectOption - Set Connection Option .................. 297 SQLSetCursorName - Set Cursor Name ....................... 303 SQLSetEnvAttr - Set Environment Attribute ..................... 306 SQLSetParam - Binds A Parameter Marker to a Buffer .............. 309 SQLSetStmtOption - Set Statement Option ..................... 314 SQLSpecialColumns - Get Special (Row Identifier) Columns ........... 319 SQLStatistics - Get Index and Statistics Information For A Base Table ..... 325 SQLTablePrivileges - Get Privileges Associated With A Table .......... 330 SQLTables - Get Table Information .......................... 334 SQLTransact - Transaction Management ...................... 338 Chapter 6. Using Advanced Features ....................... 341 Environment, Connection, and Statement Options ................. 341 Distributed Unit of Work (Coordinated Distributed Transactions) ......... 342 Querying System Catalog Information ........................ 346 Sending/Retrieving Long Data in Pieces ....................... 349 Using Arrays to Input Parameter Values ....................... 350 iv Call Level Interface Guide and Reference Retrieving A Result Set Into An Array ........................ 353 Using Stored Procedures ................................ 356 Writing Multithreaded Applications .......................... 360 Mixing Embedded SQL and DB2 CLI ......................... 366 Using Vendor Escape Clauses ............................ 369 Chapter 7. Problem Diagnosis ........................... 373 Tracing . 373 Debugging . 383 Appendix A.Programming Hints and Tips.................... 385 Avoiding Common Initialization File Problems .................... 385 Setting Common Connection Options ........................ 385 Setting Common Statement Options ......................... 385 Using SQLSetColAttributes() to Reduce Network Flow ............... 386 Comparing Binding and SQLGetData ......................... 387 Increasing Transfer Efficiency ............................. 387 Limiting Use of Catalog Functions .......................... 387 Using Column Names of Function Generated Result Sets ............ 387 Making use of Dynamic SQL Statement Caching .................. 388 Optimizing Insertion and Retrieval of Data ...................... 388 Using SQLDriverConnect Instead of SQLConnect ................. 388 Turning Off Statement Scanning ........................... 388 Problem Solving and Debugging ........................... 389 Appendix B.DB2 CLI and ODBC......................... 391 ODBC APIs and Data Types .............................. 391 ODBC Function List ................................... 393 Isolation Levels . 395 Appendix C.Extended Scalar Functions..................... 397 String Functions . 397 Date and Time Functions ............................... 398 System Functions . 399 Appendix D.Appendix D. SQLSTATE Cross Reference........... 401 Appendix E.Data Conversion . 411 Data Type Attributes .................................. 412 Converting Data from SQL to C Data Types .................... 416 Converting Data from C to SQL Data Types .................... 425 Appendix F.Example Code . 435 DB2 CLI Application ................................... 435 Stored Procedure . 464 Glossary . 485 Bibliography . 491 Index . 497 Contents v vi Call Level Interface Guide and Reference Notices References in this publication to IBM products, programs, or services do not imply that IBM