db2 v9 application programming&sql guide dsnapk13

DB2 Version 9.1 for z/OS

Application Programming and SQL Guide

SC18-9841-03

NoteBefore using this information and the product it supports, be sure to read the general information under Notices at theend of this information.

Fourth edition (December 2008)

This edition applies to DB2 Version 9.1 for z/OS (DB2 V9.1 for z/OS), product number 5635-DB2, and to anysubsequent releases until otherwise indicated in new editions. Make sure you are using the correct edition for thelevel of the product.

Specific changes are indicated by a vertical bar to the left of a change. A vertical bar to the left of a figure captionindicates that the figure has changed. Editorial changes that have no technical significance are not noted.

Copyright International Business Machines Corporation 1983, 2008.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsAbout this information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiWho should read this information . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiDB2 Utilities Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiTerminology and citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiAccessibility features for DB2 Version 9.1 for z/OS . . . . . . . . . . . . . . . . . . . . . . xivHow to send your comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvHow to read syntax diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1. Planning for and designing DB2 applications . . . . . . . . . . . . . . . 1Application and SQL release incompatibilities . . . . . . . . . . . . . . . . . . . . . . . . 1Determining the value of any SQL processing options that affect the design of your program . . . . . . . . 13Determining the binding method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Changes that invalidate plans or packages . . . . . . . . . . . . . . . . . . . . . . . . 16Determining the value of any bind options that affect the design of your program . . . . . . . . . . . 18Designing your application to promote concurrency . . . . . . . . . . . . . . . . . . . . . . 18Designing your application for recovery . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Unit of work in TSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Unit of work in CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Planning for program recovery in IMS programs . . . . . . . . . . . . . . . . . . . . . . 21Undoing selected changes within a unit of work by using savepoints . . . . . . . . . . . . . . . 28Planning for recovery of table spaces that are not logged . . . . . . . . . . . . . . . . . . . 30

Designing your application to access distributed data . . . . . . . . . . . . . . . . . . . . . 31Remote servers and distributed data . . . . . . . . . . . . . . . . . . . . . . . . . . 32Advantages of DRDA access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Preparing for coordinated updates to two or more data sources . . . . . . . . . . . . . . . . . 33Forcing restricted system rules in your program . . . . . . . . . . . . . . . . . . . . . . 34Maximizing the performance of an application that accesses distributed data . . . . . . . . . . . . 34

Chapter 2. Connecting to DB2 from your application program . . . . . . . . . . . . 45Invoking the call attachment facility . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Call attachment facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Making the CAF language interface (DSNALI) available . . . . . . . . . . . . . . . . . . . 52Requirements for programs that use CAF . . . . . . . . . . . . . . . . . . . . . . . . 53How CAF modifies the content of registers . . . . . . . . . . . . . . . . . . . . . . . . 54Implicit connections to CAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54CALL DSNALI statement parameter list . . . . . . . . . . . . . . . . . . . . . . . . . 55Summary of CAF behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57CAF connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Turning on a CAF trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69CAF return codes and reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . 69Sample CAF scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Examples of invoking CAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Invoking the Resource Recovery Services attachment facility . . . . . . . . . . . . . . . . . . . 77Resource Recovery Services attachment facility . . . . . . . . . . . . . . . . . . . . . . 79Making the RRSAF language interface (DSNRLI) available . . . . . . . . . . . . . . . . . . 83Requirements for programs that use RRSAF . . . . . . . . . . . . . . . . . . . . . . . 84How RRSAF modifies the content of registers . . . . . . . . . . . . . . . . . . . . . . . 85Implicit connections to RRSAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85CALL DSNRLI statement parameter list . . . . . . . . . . . . . . . . . . . . . . . . . 86Summary of RRSAF behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87RRSAF connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88RRSAF return codes and reason codes . . . . . . . . . . . . . . . . . . . . . . . . . 118Sample RRSAF scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Program examples for RRSAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Controlling the CICS attachment facility from an application . . . . . . . . . . . . . . . . . . 123

Copyright IBM Corp. 1983, 2008 iii

||

||

Detecting whether the CICS attachment facility is operational . . . . . . . . . . . . . . . . . 124Improving thread reuse in CICS applications . . . . . . . . . . . . . . . . . . . . . . . 124

Chapter 3. Including DB2 queries in an application program . . . . . . . . . . . . 127Declaring table and view definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . 128

DCLGEN (declarations generator) . . . . . . . . . . . . . . . . . . . . . . . . . . 129Generating table and view declarations by using DCLGEN . . . . . . . . . . . . . . . . . . 129Including declarations from DCLGEN in your program . . . . . . . . . . . . . . . . . . . 136Example: Adding DCLGEN declarations to a library . . . . . . . . . . . . . . . . . . . . 137

Defining the items that your program can use to check whether an SQL statement executed successfully . . . . 140Defining the SQL communications area. . . . . . . . . . . . . . . . . . . . . . . . . 140Declaring SQLCODE and SQLSTATE host variables . . . . . . . . . . . . . . . . . . . . 141

Defining SQL descriptor areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Declaring host variables, host variable arrays, and host structures . . . . . . . . . . . . . . . . . 144

Host variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Host variable arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Host structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Defining indicator variables, arrays, and structures . . . . . . . . . . . . . . . . . . . . . 203Declaring pointer host variables in C and C++ programs . . . . . . . . . . . . . . . . . . . 210Setting the CCSID for host variables. . . . . . . . . . . . . . . . . . . . . . . . . . 212Determining what caused an error when retrieving data into a host variable . . . . . . . . . . . . 214

Compatibility of SQL and language data types . . . . . . . . . . . . . . . . . . . . . . . 216Equivalent SQL and assembler data types . . . . . . . . . . . . . . . . . . . . . . . . 218Equivalent SQL and C data types. . . . . . . . . . . . . . . . . . . . . . . . . . . 223Equivalent SQL and COBOL data types . . . . . . . . . . . . . . . . . . . . . . . . 228Equivalent SQL and Fortran data types. . . . . . . . . . . . . . . . . . . . . . . . . 232Equivalent SQL and PL/I data types . . . . . . . . . . . . . . . . . . . . . . . . . 234Determining equivalent SQL and REXX data types . . . . . . . . . . . . . . . . . . . . . 238Data types that DB2 assigns to REXX input . . . . . . . . . . . . . . . . . . . . . . . 238

Embedding SQL statements in your application . . . . . . . . . . . . . . . . . . . . . . . 240Embedding SQL statements in assembler applications . . . . . . . . . . . . . . . . . . . . 240Embedding SQL statements in C or C++ applications . . . . . . . . . . . . . . . . . . . . 243Embedding SQL statements in COBOL applications . . . . . . . . . . . . . . . . . . . . 245Embedding SQL statements in Fortran applications. . . . . . . . . . . . . . . . . . . . . 249Embedding SQL statements in PL/I applications . . . . . . . . . . . . . . . . . . . . . 250Embedding SQL statements in REXX procedures . . . . . . . . . . . . . . . . . . . . . 253Delimiting an SQL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Rules for host variables in an SQL statement . . . . . . . . . . . . . . . . . . . . . . . 255Referencing pointer host variables in C and C++ programs . . . . . . . . . . . . . . . . . . 256Retrieving a single row of data into host variables . . . . . . . . . . . . . . . . . . . . . 257Determining whether a retrieved value in a host variable is null or truncated . . . . . . . . . . . . 259Determining whether a column value is null . . . . . . . . . . . . . . . . . . . . . . . 261Updating data by using host variables . . . . . . . . . . . . . . . . . . . . . . . . . 262Inserting a single row by using use host variables . . . . . . . . . . . . . . . . . . . . . 263Inserting null values into columns by using indicator variables or arrays . . . . . . . . . . . . . 263Host variable arrays in an SQL statement . . . . . . . . . . . . . . . . . . . . . . . . 264Retrieving multiple rows of data into host variable arrays . . . . . . . . . . . . . . . . . . 265Inserting multiple rows of data from host variable arrays. . . . . . . . . . . . . . . . . . . 265Retrieving a single row of data into a host structure . . . . . . . . . . . . . . . . . . . . 266Including dynamic SQL in your program . . . . . . . . . . . . . . . . . . . . . . . . 266Conventions used in examples of coding SQL statements. . . . . . . . . . . . . . . . . . . 305Macros for assembler applications . . . . . . . . . . . . . . . . . . . . . . . . . . 305Accessing the DB2 REXX language support application programming interfaces . . . . . . . . . . . 305Ensuring that DB2 correctly interprets character input data in REXX programs . . . . . . . . . . . 306Passing the data type of an input data type to DB2 for REXX programs . . . . . . . . . . . . . . 307Setting the isolation level of SQL statements in a REXX procedure. . . . . . . . . . . . . . . . 308

Checking the execution of SQL statements. . . . . . . . . . . . . . . . . . . . . . . . . 308Checking the execution of SQL statements by using the SQLCA . . . . . . . . . . . . . . . . 309Checking the execution of SQL statements by using SQLCODE and SQLSTATE . . . . . . . . . . . 313Checking the execution of SQL statements by using the WHENEVER statement . . . . . . . . . . . 313Checking the execution of SQL statements by using the GET DIAGNOSTICS statement . . . . . . . . 314

iv Application Programming and SQL Guide

Handling SQL error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Arithmetic and conversion errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Writing applications that enable users to create and modify tables. . . . . . . . . . . . . . . . . 327Saving SQL statements that are translated from end user requests . . . . . . . . . . . . . . . . . 328Retrieving data from DB2 tables in REXX programs . . . . . . . . . . . . . . . . . . . . . 328XML data in embedded SQL applications . . . . . . . . . . . . . . . . . . . . . . . . . 329

Host variable data types for XML data in embedded SQL applications . . . . . . . . . . . . . . 330XML column updates in embedded SQL applications . . . . . . . . . . . . . . . . . . . . 334XML data retrieval in embedded SQL applications . . . . . . . . . . . . . . . . . . . . . 337

Object-oriented extensions in COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 339Cursors and statement names in REXX . . . . . . . . . . . . . . . . . . . . . . . . . . 340Programming examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Sample dynamic and static SQL in a C program. . . . . . . . . . . . . . . . . . . . . . 341Sample COBOL dynamic SQL program. . . . . . . . . . . . . . . . . . . . . . . . . 344Sample COBOL program using DRDA access with CONNECT statements . . . . . . . . . . . . . 355Sample COBOL program using private protocol access . . . . . . . . . . . . . . . . . . . 361Sample DB2 REXX application. . . . . . . . . . . . . . . . . . . . . . . . . . . . 367Example programs that call stored procedures . . . . . . . . . . . . . . . . . . . . . . 377

Chapter 4. Creating and modifying DB2 objects . . . . . . . . . . . . . . . . . 395Creating tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Storing LOB data in a table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398Identity columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Creating tables for data integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . 403Creating work tables for the EMP and DEPT sample tables . . . . . . . . . . . . . . . . . . 412Creating created temporary tables . . . . . . . . . . . . . . . . . . . . . . . . . . 413Creating declared temporary tables . . . . . . . . . . . . . . . . . . . . . . . . . . 415

Providing a unique key for a table . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Fixing tables with incomplete definitions . . . . . . . . . . . . . . . . . . . . . . . . . 418Dropping tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419Defining a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Dropping a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421Creating a common table expression. . . . . . . . . . . . . . . . . . . . . . . . . . . 421

Common table expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422Examples of recursive common table expressions . . . . . . . . . . . . . . . . . . . . . 423

Creating triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427Invoking stored procedures and user-defined functions from triggers. . . . . . . . . . . . . . . 435Inserting, updating, and deleting data in views by using INSTEAD OF triggers . . . . . . . . . . . 436Trigger packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Trigger cascading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Order of multiple triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439Interactions between triggers and referential constraints . . . . . . . . . . . . . . . . . . . 439Interactions between triggers and tables that have multilevel security with row-level granularity . . . . . 441Triggers that return inconsistent results. . . . . . . . . . . . . . . . . . . . . . . . . 441

Sequence objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444DB2 object relational extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445Creating a distinct type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

Distinct types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446Example of distinct types, user-defined functions, and LOBs . . . . . . . . . . . . . . . . . 448

Defining a user-defined function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450User-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Components of a user-defined function definition . . . . . . . . . . . . . . . . . . . . . 455Writing an external user-defined function . . . . . . . . . . . . . . . . . . . . . . . . 457Making a user-defined function reentrant . . . . . . . . . . . . . . . . . . . . . . . . 480Using special registers in a user-defined function or a stored procedure . . . . . . . . . . . . . . 481Accessing transition tables in a user-defined function or stored procedure . . . . . . . . . . . . . 483Preparing an external user-defined function for execution . . . . . . . . . . . . . . . . . . 487Abnormal termination of an external user-defined function . . . . . . . . . . . . . . . . . . 487Saving information between invocations of a user-defined function by using a scratchpad. . . . . . . . 487

Contents v

||

||

Example of creating and using a user-defined scalar function . . . . . . . . . . . . . . . . . 489User-defined function samples that ship with DB2 . . . . . . . . . . . . . . . . . . . . . 489Determining the authorization cache size for stored procedures and user-defined functions . . . . . . . 490

Creating a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491Stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491Setting up the stored procedures environment . . . . . . . . . . . . . . . . . . . . . . 504Creating a native SQL procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 510Changing an existing version of a native SQL procedure . . . . . . . . . . . . . . . . . . . 536Regenerating an existing version of a native SQL procedure . . . . . . . . . . . . . . . . . . 536Removing an existing version of a native SQL procedure . . . . . . . . . . . . . . . . . . . 537Deploying a native SQL procedure to other DB2 for z/OS servers . . . . . . . . . . . . . . . . 537Creating an external SQL procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 538Creating an external stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . 551Creating multiple versions of external procedures and external SQL procedures . . . . . . . . . . . 563COMMIT and ROLLBACK statements in a stored procedure . . . . . . . . . . . . . . . . . 563Special registers in a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . 564Restrictions for stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 564Writing a program or stored procedure to receive the result sets from a stored procedure . . . . . . . . 564

Chapter 5. Adding and modifying data . . . . . . . . . . . . . . . . . . . . . 571Inserting data into tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

Inserting rows by using the INSERT statement . . . . . . . . . . . . . . . . . . . . . . 571Inserting data and updating data in a single operation . . . . . . . . . . . . . . . . . . . 577Selecting values while inserting data . . . . . . . . . . . . . . . . . . . . . . . . . 579

Adding data to the end of a table . . . . . . . . . . . . . . . . . . . . . . . . . . . 585Storing data that does not have a tabular format . . . . . . . . . . . . . . . . . . . . . . 586Updating table data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

Selecting values while updating data . . . . . . . . . . . . . . . . . . . . . . . . . 587Updating thousands of rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588

Deleting data from tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588Selecting values while deleting data . . . . . . . . . . . . . . . . . . . . . . . . . . 590

Chapter 6. Accessing data . . . . . . . . . . . . . . . . . . . . . . . . . . . 593Determining which tables you have access to. . . . . . . . . . . . . . . . . . . . . . . . 593Displaying information about the columns for a given table . . . . . . . . . . . . . . . . . . . 593Retrieving data by using the SELECT statement . . . . . . . . . . . . . . . . . . . . . . . 594

Selecting derived columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597Selecting XML data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597Formatting the result table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598Combining result tables from multiple SELECT statements . . . . . . . . . . . . . . . . . . 603Summarizing group values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608Finding rows that were changed within a specified period of time . . . . . . . . . . . . . . . 610Joining data from more than one table . . . . . . . . . . . . . . . . . . . . . . . . . 610Optimizing retrieval for a small set of rows . . . . . . . . . . . . . . . . . . . . . . . 621Creating recursive SQL by using common table expressions . . . . . . . . . . . . . . . . . . 622Updating data as it is retrieved from the database . . . . . . . . . . . . . . . . . . . . . 623Avoiding decimal arithmetic errors . . . . . . . . . . . . . . . . . . . . . . . . . . 623Implications of using SELECT * . . . . . . . . . . . . . . . . . . . . . . . . . . . 624Subqueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625Restrictions when using distinct types with UNION, EXCEPT, and INTERSECT . . . . . . . . . . . 633Comparison of distinct types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634Nested SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635

Retrieving a set of rows by using a cursor . . . . . . . . . . . . . . . . . . . . . . . . . 636Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637Accessing data by using a row-positioned cursor . . . . . . . . . . . . . . . . . . . . . 641Accessing data by using a rowset-positioned cursor . . . . . . . . . . . . . . . . . . . . 646Retrieving rows by using a scrollable cursor . . . . . . . . . . . . . . . . . . . . . . . 651Accessing XML or LOB data quickly by using FETCH WITH CONTINUE . . . . . . . . . . . . . 656Determining the attributes of a cursor by using the SQLCA . . . . . . . . . . . . . . . . . . 659Determining the attributes of a cursor by using the GET DIAGNOSTICS statement . . . . . . . . . . 660

vi Application Programming and SQL Guide

||

||

||

||

||

||||||

||

Scrolling through previously retrieved data . . . . . . . . . . . . . . . . . . . . . . . 660Updating previously retrieved data . . . . . . . . . . . . . . . . . . . . . . . . . . 662FETCH statement interaction between row and rowset positioning . . . . . . . . . . . . . . . 662Examples of fetching rows by using cursors . . . . . . . . . . . . . . . . . . . . . . . 663

Specifying direct row access by using row IDs . . . . . . . . . . . . . . . . . . . . . . . 668ROWID columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

Ways to manipulate LOB data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670LOB host variable, LOB locator, and LOB file reference variable declarations . . . . . . . . . . . . 671LOB materialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677Saving storage when manipulating LOBs by using LOB locators . . . . . . . . . . . . . . . . 677Deferring evaluation of a LOB expression to improve performance . . . . . . . . . . . . . . . 679LOB file reference variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

Referencing a sequence object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683Retrieving thousands of rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684Determining when a row was changed . . . . . . . . . . . . . . . . . . . . . . . . . . 684Checking whether an XML column contains a certain value . . . . . . . . . . . . . . . . . . . 685Accessing DB2 data that is not in a table . . . . . . . . . . . . . . . . . . . . . . . . . 685Ensuring that queries perform sufficiently . . . . . . . . . . . . . . . . . . . . . . . . . 685Items to include in a batch DL/I program . . . . . . . . . . . . . . . . . . . . . . . . . 686

Chapter 7. Invoking a user-defined function . . . . . . . . . . . . . . . . . . . 689Determining the authorization ID for invoking user-defined functions . . . . . . . . . . . . . . . 690Ensuring that DB2 executes the intended user-defined function. . . . . . . . . . . . . . . . . . 691

Function resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692Checking how DB2 resolves functions by using DSN_FUNCTION_TABLE . . . . . . . . . . . . . 695

Restrictions when passing arguments with distinct types to functions . . . . . . . . . . . . . . . 698Cases when DB2 casts arguments for a user-defined function . . . . . . . . . . . . . . . . . . 699Maximizing the number of user-defined functions and stored procedures that can run concurrently . . . . . 701

Chapter 8. Calling a stored procedure from your application . . . . . . . . . . . . 703Parameter list for stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 706Linkage conventions for stored procedures . . . . . . . . . . . . . . . . . . . . . . . . 707Improving stored procedure performance by using indicator variables . . . . . . . . . . . . . . . 722Compatible data types for parameters that are passed to stored procedures . . . . . . . . . . . . . 723Preparing a client program for a stored procedure . . . . . . . . . . . . . . . . . . . . . . 731How DB2 determines which stored procedure to run . . . . . . . . . . . . . . . . . . . . . 732Calling different versions of a stored procedure from a single application . . . . . . . . . . . . . . 732Invoking multiple instances of a stored procedure . . . . . . . . . . . . . . . . . . . . . . 733Stored procedures that access non-DB2 resources . . . . . . . . . . . . . . . . . . . . . . 734Designating the active version of a native SQL procedure . . . . . . . . . . . . . . . . . . . 735Temporarily overriding the active version of a native SQL procedure . . . . . . . . . . . . . . . . 736Specifying the number of stored procedures that can run concurrently . . . . . . . . . . . . . . . 736DB2-supplied stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737

WLM environment refresh stored procedure (WLM_REFRESH) . . . . . . . . . . . . . . . . 739DSNACICS stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741DSNAIMS stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749The DB2 EXPLAIN stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . 754Deprecated: Store an XML document from an MQ message queue in DB2 tables (DXXMQINSERT) . . . . 756Deprecated: Store an XML document from an MQ message queue in DB2 tables (DXXMQSHRED) . . . . . 759Deprecated: Store a large XML document from an MQ message queue in DB2 tables (DXXMQINSERTCLOB) 761Deprecated: Store a large XML document from an MQ message queue in DB2 tables (DXXMQSHREDCLOB) 764Deprecated: Store XML documents from an MQ message queue in DB2 tables (DXXMQINSERTALL) . . . . 766Deprecated: Store XML documents from an MQ message queue in DB2 tables (DXXMQSHREDALL) . . . . 768Deprecated: Store large XML documents from an MQ message queue in DB2 tables(DXXMQSHREDALLCLOB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771Deprecated: Store large XML documents from an MQ message queue in DB2 tables(DXXMQINSERTALLCLOB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773Deprecated: Send XML documents to an MQ message queue (DXXMQGEN) . . . . . . . . . . . . 776Deprecated: Send XML documents to an MQ message queue (DXXMQRETRIEVE) . . . . . . . . . . 779Deprecated: Send large XML documents to an MQ message queue (DXXMQGENCLOB) . . . . . . . . 783

Contents vii

||

||||

||

Deprecated: Send XML documents to an MQ message queue (DXXMQRETRIEVECLOB) . . . . . . . . 787The XML schema registration stored procedure (XSR_REGISTER) . . . . . . . . . . . . . . . . 790The add XML schema document stored procedure (XSR_ADDSCHEMADOC). . . . . . . . . . . . 792The XML schema registration completion stored procedure (XSR_COMPLETE) . . . . . . . . . . . 793The XML schema removal stored procedure (XSR_REMOVE) . . . . . . . . . . . . . . . . . 795The XML decomposition stored procedure (XDBDECOMPXML) . . . . . . . . . . . . . . . . 796

Chapter 9. Coding methods for distributed data . . . . . . . . . . . . . . . . . 799Accessing distributed data by using three-part table names . . . . . . . . . . . . . . . . . . . 799

Accessing remote declared temporary tables by using three-part table names . . . . . . . . . . . . 801Accessing distributed data by using explicit CONNECT statements . . . . . . . . . . . . . . . . 801

Specifying a location alias name for multiple sites . . . . . . . . . . . . . . . . . . . . . 802Releasing connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

Transmitting mixed data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803Identifying the server at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . 803SQL limitations at dissimilar servers. . . . . . . . . . . . . . . . . . . . . . . . . . . 804Support for executing long SQL statements in a distributed environment . . . . . . . . . . . . . . 804Distributed queries against ASCII or Unicode tables . . . . . . . . . . . . . . . . . . . . . 805Restrictions when using scrollable cursors to access distributed data . . . . . . . . . . . . . . . . 805Restrictions when using rowset-positioned cursors to access distributed data . . . . . . . . . . . . . 806WebSphere MQ with DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806

WebSphere MQ messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806DB2 MQ functions and DB2 MQ XML stored procedures . . . . . . . . . . . . . . . . . . . 810Generating XML documents from existing tables and sending them to an MQ message queue . . . . . . 816Shredding XML documents from an MQ message queue . . . . . . . . . . . . . . . . . . . 816DB2 MQ tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816Converting applications to use the MQI functions . . . . . . . . . . . . . . . . . . . . . 825Basic messaging with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . 826Sending messages with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . 827Retrieving messages with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . 827Application to application connectivity with WebSphere MQ . . . . . . . . . . . . . . . . . 829Asynchronous messaging in DB2 for z/OS . . . . . . . . . . . . . . . . . . . . . . . 832

Chapter 10. DB2 as a Web services consumer and provider . . . . . . . . . . . . 845The SOAPHTTPV and SOAPHTTPC user-defined functions . . . . . . . . . . . . . . . . . . . 845The SOAPHTTPNV and SOAPHTTPNC user-defined functions . . . . . . . . . . . . . . . . . 847SQLSTATEs for DB2 as a Web services consumer . . . . . . . . . . . . . . . . . . . . . . 847

Chapter 11. Preparing an application to run on DB2 for z/OS . . . . . . . . . . . . 851Setting the DB2I defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853Processing SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854

Processing SQL statements by using the DB2 precompiler . . . . . . . . . . . . . . . . . . 856Processing SQL statements by using the DB2 coprocessor. . . . . . . . . . . . . . . . . . . 862Translating command-level statements in a CICS program . . . . . . . . . . . . . . . . . . 865Differences between the DB2 precompiler and the DB2 coprocessor . . . . . . . . . . . . . . . 866Options for SQL statement processing . . . . . . . . . . . . . . . . . . . . . . . . . 867Program preparation options for remote packages . . . . . . . . . . . . . . . . . . . . . 877

Compiling and link-editing an application. . . . . . . . . . . . . . . . . . . . . . . . . 879Binding an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880

Binding a DBRM to a package. . . . . . . . . . . . . . . . . . . . . . . . . . . . 881Binding an application plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886Bind process for remote access . . . . . . . . . . . . . . . . . . . . . . . . . . . 890Binding a batch program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894Converting an existing plan into packages to run remotely . . . . . . . . . . . . . . . . . . 894Setting the program level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895DYNAMICRULES bind option . . . . . . . . . . . . . . . . . . . . . . . . . . . 896Determining the authorization cache size for plans . . . . . . . . . . . . . . . . . . . . . 897Determining the authorization cache size for packages . . . . . . . . . . . . . . . . . . . 898Dynamic plan selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898

Rebinding an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900

viii Application Programming and SQL Guide

||||||||

||

||

Rebinding a package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900Rebinding a plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901Rebinding lists of plans and packages . . . . . . . . . . . . . . . . . . . . . . . . . 902Generating lists of REBIND commands . . . . . . . . . . . . . . . . . . . . . . . . . 902Automatic rebinding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908

Specifying the rules that apply to SQL behavior at run time . . . . . . . . . . . . . . . . . . . 910DB2 program preparation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 911Input and output data sets for DL/I batch jobs . . . . . . . . . . . . . . . . . . . . . . . 913DB2-supplied JCL procedures for preparing an application . . . . . . . . . . . . . . . . . . . 916

JCL to include the appropriate interface code when using the DB2-supplied JCL procedures . . . . . . . 916Tailoring DB2-supplied JCL procedures for preparing CICS programs . . . . . . . . . . . . . . 917

DB2I primary option menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918DB2I panels that are used for program preparation . . . . . . . . . . . . . . . . . . . . . . 919

DB2 Program Preparation panel . . . . . . . . . . . . . . . . . . . . . . . . . . . 921DB2I Defaults Panel 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925DB2I Defaults Panel 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927Precompile panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928Bind Package panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931Bind Plan panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934Defaults for Bind Package panel and Defaults for Bind Plan panel. . . . . . . . . . . . . . . . 937System Connection Types panel . . . . . . . . . . . . . . . . . . . . . . . . . . . 942Panels for entering lists of values. . . . . . . . . . . . . . . . . . . . . . . . . . . 943Program Preparation: Compile, Link, and Run panel . . . . . . . . . . . . . . . . . . . . 944

DB2I panels that are used to rebind and free plans and packages . . . . . . . . . . . . . . . . . 946Bind/Rebind/Free Selection panel . . . . . . . . . . . . . . . . . . . . . . . . . . 946Rebind Package panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948Rebind Trigger Package panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949Rebind Plan panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951Free Package panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953Free Plan panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954

Chapter 12. Running an application on DB2 for z/OS . . . . . . . . . . . . . . . 955DSN command processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955DB2I Run panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956Running a program in TSO foreground. . . . . . . . . . . . . . . . . . . . . . . . . . 957Running a DB2 REXX application . . . . . . . . . . . . . . . . . . . . . . . . . . . 958Invoking programs through the Interactive System Productivity Facility . . . . . . . . . . . . . . . 958

ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959Invoking a single SQL program through ISPF and DSN . . . . . . . . . . . . . . . . . . . 960Invoking multiple SQL programs through ISPF and DSN. . . . . . . . . . . . . . . . . . . 961

Loading and running a batch program . . . . . . . . . . . . . . . . . . . . . . . . . . 962Authorization for running a batch DL/I program . . . . . . . . . . . . . . . . . . . . . 963Restarting a batch program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963

Running stored procedures from the command line processor . . . . . . . . . . . . . . . . . . 966Command line processor CALL statement . . . . . . . . . . . . . . . . . . . . . . . . 966

Example of running a batch DB2 application in TSO . . . . . . . . . . . . . . . . . . . . . 967Example of calling applications in a command procedure . . . . . . . . . . . . . . . . . . . 968

Chapter 13. Testing and debugging an application program on DB2 for z/OS . . . . . 971Designing a test data structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971

Analyzing application data needs . . . . . . . . . . . . . . . . . . . . . . . . . . 971Authorization for test tables and applications. . . . . . . . . . . . . . . . . . . . . . . 972Example SQL statements to create a comprehensive test structure . . . . . . . . . . . . . . . . 973

Populating the test tables with data . . . . . . . . . . . . . . . . . . . . . . . . . . . 974Methods for testing SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 974Executing SQL by using SPUFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975

SPUFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978Content of a SPUFI input data set . . . . . . . . . . . . . . . . . . . . . . . . . . 979The SPUFI panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979Changing SPUFI defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981

Contents ix

||||

Setting the SQL terminator character in a SPUFI input data set . . . . . . . . . . . . . . . . . 986Controlling toleration of warnings in SPUFI . . . . . . . . . . . . . . . . . . . . . . . 987Output from SPUFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987

Testing an external user-defined function . . . . . . . . . . . . . . . . . . . . . . . . . 989Testing a user-defined function by using the Debug Tool for z/OS . . . . . . . . . . . . . . . 989Testing a user-defined function by routing the debugging messages to SYSPRINT . . . . . . . . . . 991Testing a user-defined function by using driver applications. . . . . . . . . . . . . . . . . . 991Testing a user-defined function by using SQL INSERT statements . . . . . . . . . . . . . . . . 992

Debugging a stored procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992Debugging stored procedures with the Debug Tool and IBM VisualAge COBOL . . . . . . . . . . . 993Debugging a C language stored procedure with the Debug Tool and C/C++ Productivity Tools for z/OS . . 994Debugging with the Unified Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 994Debugging stored procedures with the Debug Tool for z/OS . . . . . . . . . . . . . . . . . 995Recording stored procedure debugging messages in a file . . . . . . . . . . . . . . . . . . 997Driver applications for debugging procedures . . . . . . . . . . . . . . . . . . . . . . 997DB2 tables that contain debugging information . . . . . . . . . . . . . . . . . . . . . . 997

Debugging an application program . . . . . . . . . . . . . . . . . . . . . . . . . . . 998Locating the problem in an application . . . . . . . . . . . . . . . . . . . . . . . . . 998Techniques for debugging programs in TSO . . . . . . . . . . . . . . . . . . . . . . . 1003Techniques for debugging programs in IMS . . . . . . . . . . . . . . . . . . . . . . . 1003Techniques for debugging programs in CICS . . . . . . . . . . . . . . . . . . . . . . 1004

Finding a violated referential or check constraint . . . . . . . . . . . . . . . . . . . . . . 1008

Chapter 14. DB2 sample applications and data . . . . . . . . . . . . . . . . . 1009DB2 sample tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009

Activity table (DSN8910.ACT) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009Department table (DSN8910.DEPT) . . . . . . . . . . . . . . . . . . . . . . . . . . 1010Employee table (DSN8910.EMP) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011Employee photo and resume table (DSN8910.EMP_PHOTO_RESUME) . . . . . . . . . . . . . . 1015Project table (DSN8910.PROJ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016Project activity table (DSN8910.PROJACT) . . . . . . . . . . . . . . . . . . . . . . . 1017Employee to project activity table (DSN8910.EMPPROJACT) . . . . . . . . . . . . . . . . . 1018Unicode sample table (DSN8910.DEMO_UNICODE) . . . . . . . . . . . . . . . . . . . . 1019Relationships among the sample tables . . . . . . . . . . . . . . . . . . . . . . . . 1020Views on the sample tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021Storage of sample application tables . . . . . . . . . . . . . . . . . . . . . . . . . 1025

DB2 sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029Types of sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031Application languages and environments for the sample applications . . . . . . . . . . . . . . 1033Sample applications in TSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034Sample applications in IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036Sample applications in CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037DSNTIAUL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037DSNTIAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042DSNTEP2 and DSNTEP4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044

Information resources for DB2 for z/OS and related products . . . . . . . . . . . 1049

How to obtain DB2 information . . . . . . . . . . . . . . . . . . . . . . . . 1055

How to use the DB2 library . . . . . . . . . . . . . . . . . . . . . . . . . . 1059

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063Programming Interface Information . . . . . . . . . . . . . . . . . . . . . . . . . . 1064

General-use Programming Interface and Associated Guidance Information . . . . . . . . . . . . 1064Product-sensitive Programming Interface and Associated Guidance Information. . . . . . . . . . . 1065

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067

x Application Programming and SQL Guide

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111

Contents xi

xii Application Programming and SQL Guide

About this informationThis information discusses how to design and write application programs thataccess DB2 for z/OS (DB2), a highly flexible relational database managementsystem (DBMS).

Visit the following Web site for information about ordering DB2 books andobtaining other valuable information about DB2 for z/OS: http://publib.boulder.ibm.com/infocenter/imzic

This information assumes that your DB2 subsystem is running in Version 9.1new-function mode. Generally, new functions that are described, including changesto existing functions, statements, and limits, are available only in new-functionmode. Two exceptions to this general statement are new and changed utilities andoptimization enhancements, which are also available in conversion mode unlessstated otherwise.

Who should read this informationThis information is for DB2 application developers who are familiar withStructured Query Language (SQL) and who know one or more programminglanguages that DB2 supports.

DB2 Utilities SuiteImportant: In this version of DB2 for z/OS, the DB2 Utilities Suite is available asan optional product. You must separately order and purchase a license to suchutilities, and discussion of those utility functions in this publication is not intendedto otherwise imply that you have a license to them.

The DB2 Utilities Suite is designed to work with the DFSORT program, whichyou are licensed to use in support of the DB2 utilities even if you do not otherwiselicense DFSORT for general use. If your primary sort product is not DFSORT,consider the following informational APARs mandatory reading:v II14047/II14213: USE OF DFSORT BY DB2 UTILITIESv II13495: HOW DFSORT TAKES ADVANTAGE OF 64-BIT REALARCHITECTURE

These informational APARs are periodically updated.Related information

DB2 utilities packaging (Utility Guide)

Terminology and citationsIn this information, DB2 Version 9.1 for z/OS is referred to as DB2 for z/OS. Incases where the context makes the meaning clear, DB2 for z/OS is referred to asDB2. When this information refers to titles of DB2 for z/OS books, a short title isused. (For example, See DB2 SQL Reference is a citation to IBM DB2 Version 9.1for z/OS SQL Reference.)

Copyright IBM Corp. 1983, 2008 xiii

When referring to a DB2 product other than DB2 for z/OS, this information usesthe products full name to avoid ambiguity.

The following terms are used as indicated:

DB2 Represents either the DB2 licensed program or a particular DB2 subsystem.

OMEGAMON

Refers to any of the following products:v IBM Tivoli OMEGAMON XE for DB2 Performance Expert on z/OSv IBM Tivoli OMEGAMON XE for DB2 Performance Monitor on z/OSv IBM DB2 Performance Expert for Multiplatforms and Workgroupsv IBM DB2 Buffer Pool Analyzer for z/OS

C, C++, and C languageRepresent the C or C++ programming language.

CICS Represents CICS Transaction Server for z/OS.

IMS Represents the IMS Database Manager or IMS Transaction Manager.

MVS Represents the MVS element of the z/OS operating system, which isequivalent to the Base Control Program (BCP) component of the z/OSoperating system.

RACF

Represents the functions that are provided by the RACF component of thez/OS Security Server.

Accessibility features for DB2 Version 9.1 for z/OSAccessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use information technology products successfully.

Accessibility features

The following list includes the major accessibility features in z/OS products,including DB2 Version 9.1 for z/OS. These features support:v Keyboard-only operation.v Interfaces that are commonly used by screen readers and screen magnifiers.v Customization of display attributes such as color, contrast, and font size

Tip: The Information Management Software for z/OS Solutions InformationCenter (which includes information for DB2 Version 9.1 for z/OS) and its relatedpublications are accessibility-enabled for the IBM Home Page Reader. You canoperate all features using the keyboard instead of the mouse.

Keyboard navigation

You can access DB2 Version 9.1 for z/OS ISPF panel functions by using a keyboardor keyboard shortcut keys.

For information about navigating the DB2 Version 9.1 for z/OS ISPF panels usingTSO/E or ISPF, refer to the z/OS TSO/E Primer, the z/OS TSO/E Users Guide, andthe z/OS ISPF Users Guide. These guides describe how to navigate each interface,including the use of keyboard shortcuts or function keys (PF keys). Each guideincludes the default settings for the PF keys and explains how to modify theirfunctions.

xiv Application Programming and SQL Guide

|

Related accessibility information

Online documentation for DB2 Version 9.1 for z/OS is available in the InformationManagement Software for z/OS Solutions Information Center, which is available atthe following Web site: http://publib.boulder.ibm.com/infocenter/dzichelp

IBM and accessibility

See the IBM Accessibility Center at http://www.ibm.com/able for more informationabout the commitment that IBM has to accessibility.

How to send your commentsYour feedback helps IBM to provide quality information. Please send anycomments that you have about this book or other DB2 for z/OS documentation.You can use the following methods to provide comments:v Send your comments by e-mail to [email protected] and include the nameof the product, the version number of the product, and the number of the book.If you are commenting on specific text, please list the location of the text (forexample, a chapter and section title or a help topic title).

v You can send comments from the Web. Visit the DB2 for z/OS - TechnicalResources Web site at:

http://www.ibm.com/support/docview.wss?&uid=swg27011656

This Web site has an online reader comment form that you can use to sendcomments.

v You can also send comments by using the feedback link at the footer of eachpage in the Information Management Software for z/OS Solutions InformationCenter at http://publib.boulder.ibm.com/infocenter/db2zhelp.

How to read syntax diagramsCertain conventions apply to the syntax diagrams that are used in IBMdocumentation.

Apply the following rules when reading the syntax diagrams that are used in DB2for z/OS documentation:v Read the syntax diagrams from left to right, from top to bottom, following thepath of the line.The symbol indicates the beginning of a statement.The symbol indicates that the statement syntax is continued on the nextline.The symbol indicates that a statement is continued from the previous line.The symbol indicates the end of a statement.

v Required items appear on the horizontal line (the main path).

required_item

v Optional items appear below the main path.

About this information xv

required_itemoptional_item

If an optional item appears above the main path, that item has no effect on theexecution of the statement and is used only for readability.

optional_item

required_item

v If you can choose from two or more items, they appear vertically, in a stack.If you must choose one of the items, one item of the stack appears on the mainpath.

required_item required_choice1required_choice2

If choosing one of the items is optional, the entire stack appears below the mainpath.

required_itemoptional_choice1optional_choice2

If one of the items is the default, it appears above the main path and theremaining choices are shown below.

required_itemdefault_choice

optional_choiceoptional_choice

v An arrow returning to the left, above the main line, indicates an item that can berepeated.

required_item repeatable_item

If the repeat arrow contains a comma, you must separate repeated items with acomma.

required_item

,

repeatable_item

A repeat arrow above a stack indicates that you can repeat the items in thestack.

v Sometimes a diagram must be split into fragments. The syntax fragment isshown separately from the main syntax diagram, but the contents of thefragment should be read as if they are on the main path of the diagram.

required_item fragment-name

xvi Application Programming and SQL Guide

|||||||||||||||||

fragment-name:

required_itemoptional_name

v With the exception of XPath keywords, keywords appear in uppercase (forexample, FROM). Keywords must be spelled exactly as shown. XPath keywordsare defined as lowercase names, and must be spelled exactly as shown. Variablesappear in all lowercase letters (for example, column-name). They representuser-supplied names or values.

v If punctuation marks, parentheses, arithmetic operators, or other such symbolsare shown, you must enter them as part of the syntax.

About this information xvii

|||||||||||||||||||||

xviii Application Programming and SQL Guide

Chapter 1. Planning for and designing DB2 applicationsWhether you are writing a new DB2 application or migrating an existingapplication from a previous release of DB2, you need to make some planning anddesign decisions before you write or run the program.

If you are migrating an existing application from a previous release of DB2, readthe application and SQL release incompatibilities and make any necessary changesin the application.

If you are writing a new DB2 application, first determine the following items:v the value of some of the SQL processing optionsv the binding methodv the value of some of the bind optionsThen make sure that your program implements the appropriate recommendationsso that it promotes concurrency, can handle recovery and restart situations, and canefficiently access distributed data.

Application and SQL release incompatibilitiesWhen you migrate to Version 9.1, be aware of the following application and SQLrelease incompatibilities.

Changes in BIND PACKAGE and BIND PLAN defaults

The default value for bind option CURRENTDATA is changed from YES to NO.This applies to the BIND PLAN and the BIND PACKAGE subcommands, as wellas the CREATE TRIGGER for trigger packages, and the CREATE PROCEDURE andthe ALTER PROCEDURE ADD VERSION SQL statements for SQL PL procedurepackages. Specifying NO for CURRENTDATA is the best option for performance.

The default value for bind option ISOLATION is changed from RR to CS. Thisapplies to the BIND PLAN and the remote BIND PACKAGE subcommands. Forthe BIND PACKAGE subcommand, the current default (plan value) stays. Thedefault change does not apply to implicitly-built CTs (for example, DISTSERV CTs).

Although you can specify DBPROTOCOL(PRIVATE) for the DBPROTOCOLparameter of the BIND option, DB2 issues a new warning message, DSNT226I.

All BIND statements for plans and packages that are bound during the installationor migration process specify the ISOLATION parameter explicitly, except forroutines that do not fetch data. The current settings are maintained forcompatibility.

Plan for the XML data type

Drop any user-defined data types with the name XML to prevent problems withthe new Version 9 built-in XML data type. You can recreate the existinguser-defined data types with new names.

Copyright IBM Corp. 1983, 2008 1

|||||||||||||||||||||||

Changes to XMLNAMESPACES

In Version 8, in the XMLNAMESPACES function, if the XML-namespace-uriargument had a value of http://www.w3.org/XML/1998/namespace orhttp://www.w3.org/2000/xmlns/, DB2 did not issue an error. In Version 9.1,starting in conversion mode, DB2 issues an error.

Changes to serialization of empty elements

In Version 8, DB2 serialized empty XML elements in a different way than itserializes them in Version 9.1. In Version 8, empty element a was serialized as. In Version 9.1, starting in conversion mode, empty element a isserialized as .

Availability of LOB or XML values in JDBC or SQLJ applicationswith progressive streaming

In previous releases, if a JDBC or SQLJ application retrieved LOB data into anapplication variable, the contents of the application variable were still availableafter the cursor was moved or closed. DB2 Version 9.1 for z/OS supportsstreaming. The IBM Data Server Driver for JDBC and SQLJ uses progressivestreaming as the default for retrieval of LOB or XML values. When progressivestreaming is in effect, the contents of LOB or XML variables are no longer availableafter the cursor is moved or closed.

Adjust applications that depend on error information that isreturned from DB2-supplied stored procedures

Adjust any applications that call one of the following stored procedures and thencheck and process the specific SQLCODE or SQLSTATE that is returned by theCALL statement:v SQLJ.INSTALL_JARv SQLJ.REMOVE_JARv SQLJ.REPLACE_JARv SQLJ.DB2_INSTALL_JARv SQLJ.DB2_REPLACE_JARv SQLJ.DB2_REMOVE_JARv SQLJ.DB2_UPDATEJARINFO

In Version 9.1, these stored procedures return more meaningful SQLCODEs andSQLSTATEs than they returned in previous releases of DB2. The other input andoutput parameters of these stored procedures have not changed.

For example, the following application needs to change, because the SQLCODEthat is returned is no longer -20201. Successful execution (SQLCODE 0) is notaffected.CALL SQLJ.REMOVE_JAR(...)IF (SQLCODE = -20201) THENDO;...END;

2 Application Programming and SQL Guide

||||||||||||||||||||||||||||||||||||||||||

Qualify user-defined function names

If you use a user-defined function that has the same name as a built in functionthat has been added to Version 9.1, ensure that you fully qualify the functionname. If the function name is unqualified and SYSIBM precedes the schema thatyou used for this function in the SQL path, DB2 invokes one of the built-infunctions. For a list of built-in functions, including those that have been added inVersion 9.1, see the topic Functions.

Fully define objectsEnsure that you do not have any incomplete object definitions in your DB2 Version8 catalog. For example, if a table has a primary or unique key defined but theenforcing primary or unique key index does not exist, the table definition isconsidered incomplete. You need to complete or drop all such objects before youbegin migration because their behavior will be different in Version 9.1. Forexample, if you attempt to create an enforcing primary key index to complete atable definition in Version 9.1 and the residing table space is implicitly created, theindex will be treated as a regular index instead of an enforcing index.

SQL reserved words

Version 9.1 has several new SQL reserved words. Refer to DB2 SQL Reference forthe list, and adjust your applications accordingly.

Changes to PL/I applications with no DECLARE VARIABLEstatements

For PL/I applications with no DECLARE VARIABLE statements, the rules for hostvariables and string constants in the FROM clause of a PREPARE or EXECUTEIMMEDIATE statement have changed. A host variable must be a varying-lengthstring variable that is preceded by a colon. A PL/I string cannot be preceded by acolon.

Automatic rebind of plans and packages created before DB2Version 4

If you have plans and packages that were bound before DB2 Version 4 and youspecified YES or COEXIST in the AUTO BIND field of panel DSNTIPO, DB2Version 9.1 autobinds these packages. Thus, you might experience an executiondelay the first time that such a plan is loaded. Also, DB2 might change the accesspath due to the autobind, potentially resulting in a more efficient access path.

If you specified NO in the AUTO BIND field of panel DSNTIPO, DB2 Version 9.1returns SQLCODE -908, SQLSTATE 23510 for each attempt to use such a packageor plan until it is rebound.

Changed behavior of the INSERT statement with theOVERRIDING USER VALUES clause

When the INSERT statement is specified with the OVERRIDING USER VALUESclause, the value for the insert operation is ignored for columns that are definedwith the GENERATED BY DEFAULT attribute.

Chapter 1. Planning for and designing DB2 applications 3

|||||||||||||||||||||||||||||||||||||||||

DESCRIBE no longer returns LONG type values

Because DB2 no longer stores LONG type values in the catalog, when you executea DESCRIBE statement against a column with a LONG VARCHAR or LONGVARGRAPHIC data type, the DESCRIBE statement returns the values asVARCHAR or VARGRAPHIC data type.

The DSNTIAUL sample program was updated through APAR PK46518 to accountfor this change. You need to apply APAR PK46518 and precompile, bind compile,and link-edit DSNTIAUL to make it compatible with the changed DESCRIBEbehavior.

DB2 enforces the restrictions about where a host variable arraycan be specified

host-variable-array is the meta-variable for host variable arrays in syntax diagrams.host-variable-array is included only in the syntax for multi-row FETCH, multi-rowINSERT, multi-row MERGE, and EXECUTE in support of a dynamic multi-rowINSERT or MERGE statement. host-variable-array is not included in the syntaxdiagram for expression , so a host variable array cannot be used in other contexts.In previous releases, if you specified host-variable-array in an unsupported context,you received no errors. In Version 9.1, if a host variable array is referenced in anunsupported context, DB2 issues an error.

For more information about where you can specify the host-variable-array variable,see DB2 SQL Reference.

DEBUGSESSION system privilege required for continueddebugging of SQL procedures

After you migrate to new-function mode, users that debug external SQLprocedures need the DEBUGSESSION system privilege. (External SQL procedureswere previously called SQL procedures in Version 8.) Only users of the newUnified Debugger enabled client platforms need this system privilege. Users of theVersion 8 SQL Debugger-enabled client platforms do not need this systemprivilege.

Changes to the result length of the DECRYPT function

The result length of the DECRYPT function is shortened to 8 bytes less than thelength of the input value. If the result expands because of a difference betweeninput and result CCSIDs, you must cast the encrypted data to a larger VARCHARvalue before the DECRYPT function is run.

COLTYPE column in SYSIBM.SYSCOLUMNS andSYSIBM.SYSCOLUMNS_HIST for LONG column types

When new tables are created with LONG VARCHAR or LONG VARGRAPHICcolumns, the COLTYPE values in SYSIBM.SYSCOLUMNS andSYSIBM.SYSCOLUMNS_HIST contain VARCHAR or VARG.


|||||||||||||||||||||||||||||||||||||||

CREATEDBY column in SYSIBM.SYSDATATYPES,SYSIBM.SYSROUTINES, SYSIBM.SYSSEQUENCES, andSYSIBM.SYSTRIGGERS

The CREATEDBY column might contain a different value than in previous releasesof DB2. The column might contain a different value in static CREATE statementsfor distinct types, functions, and procedures or when a dynamic SQL statementsets the CURRENT SQLID value to a value other than USER.

Drop and recreate SYSPROC.DSNWZP

Drop and recreate SYSPROC.DSNWZP as part of running job DSNTIJSG or alter itto specify READS SQL DATA, as shown in the following SQL statement:ALTER PROCEDURE SYSPROC.DSNWZP READS SQL DATA;

On data sharing systems, SYSPROC.DSNWZP needs to be dropped and recreatedas part of migrating the first member, but not for subsequent members. DSNTIJSGgrants execute access on DSNWZP to PUBLIC. If necessary, change PUBLIC to aspecific authorization ID.

DB2 returns all DSNWZP output in the same format as DB2parameters

In previous releases, DSNWZP returned the current setting of several systemparameters in a format other than the one used by the system parameter macros.For example, DSN6SPRM expected the setting for EDMPOOL in kilobytes, andDSNWZP returned it in bytes. In Version 9.1, DB2 returns all DSNWZP output inthe same format as DB2 parameters. Modify programs that call DSNWZP if theycompensate for the format differences.

DB2 enforces the restriction that row IDs are not compatible withcharacter strings when they are used with a set operator

In previous releases, DB2 did not always enforce the restriction that row IDs arenot compatible with character strings. In Version 9.1, DB2 enforces the restrictionthat row IDs are not compatible with string types when they are used with a setoperator (UNION, INTERSECT, or EXCEPT).

You can no longer explicitly create a database name asDSNxxxxx

After you migrate to conversion mode, if you explicitly create a database namewith eight characters that begins with DSN and is followed by exactly five digits,DB2 issues an SQLCODE -20074 (SQLSTATE 42939).

Database privileges on the DSNDB04 database now give youthose privileges on all implicitly-created databases

Because database privileges on the DSNDB04 database now give you thoseprivileges on all implicitly created databases, careful consideration is needed beforeyou grant database privileges on DSNDB04. For example, in Version 9.1, if youhave the STOPDB privilege on DSNDB04, you also have the STOPDB privilege onall implicitly-created databases.


|||||||||||||||||||||||||||||||||||||||||

Implicitly-created objects that are associated with LOB columnsrequire additional privileges

In previous releases, implicitly-created objects that are associated with LOBcolumns did not require CREATETAB and CREATETS privileges on the databaseof the base table or USE privilege on the buffer pool and storage group that isused by the LOB objects. In Version 9.1, these privileges are required.

Adjust applications to use LRHCLR instead of LGDISCLRThe LGDISCLR field in the DSNDQJ00 macro has been removed. Updateapplications that used the LGDISCLR value in the DSNDQJ00 mapping macro todetermine whether a log record is a compensation log record to use the LRHCLRvalue instead.

Changed behavior for the CREATE statement

You can no longer create databases with the AS TEMP clause or table spaces thatspecify TEMP as the target database. The TEMP database is no longer used byDB2. The WORKFILE database is the only temporary database.

The DECLARE statement and the work file database

If you have applications in Version 8 that issue DECLARE SENSITIVE STATICSCROLL CURSOR or DECLARE GLOBAL TEMPORARY TABLE statements,ensure that the work file database exists and that it has at least one table spacewith a 32-KB page size to avoid errors.

Adjust monitor programs that access OP buffersAdjust assignment strategies of monitor programs that access OP buffers. InVersion 8, traces were left in a disabled state, which consumed CPU for trace datathat could not be retrieved. In Version 9.1, traces that are started with a destinationof OPX choose the next available buffer that is not in use and traces are no longerleft in a disabled state.

In addition, in Version 8, when the thread that owned an OP buffer terminated, OPtraces were left in a disabled state and could be reactivated by starting anothertrace to that buffer. In Version 9.1, if an OP buffer terminates and the onlydestinations for the trace records are OP buffers, the traces that are started to thatbuffer are stopped. If an OP buffer terminates and the trace is started to both OPand non-OP destinations, the traces that are started to that buffer are modified touse non-OP destinations only.

The message format of DSNW128I and DSNW129I has changed, so modifyautomation that is based on those message formats.

Changed behavior for system-required objectsAfter you migrate to Version 9.1 new-function mode, if the containing table spaceis implicitly-created, you cannot drop any system-required objects, except for theLOB table space, even if you explicitly created these objects in a previous release.The following statements will not work properly if the system-required objectswere implicitly created by DB2:


|||||||||||||||||||||||||||||||||||||||||

CREATE AUXILIARY TABLEIf you issue a CREATE AUXILIARY TABLE statement and an auxiliarytable that was implicitly created by DB2 already exists for the same basetable, the CREATE AUXILIARY TABLE statement fails and DB2 issuesSQLCODE -646, SQLSTATE 55017, and reason code 3.

CREATE LOB TABLESPACEIf you issue a CREATE LOB TABLESPACE statement to create a LOB tablespace in an implicitly created database, the CREATE LOB TABLESPACEstatement fails and DB2 issues SQLCODE -20355, SQLSTATE 429BW, andreason code 1.

CREATE DATABASEIf you specify a database name with eight characters that begins with DSNand is followed by exactly five digits in a CREATE DATABASE statement,the CREATE DATABASE statement fails and DB2 issues SQLCODE -20074,SQLSTATE 42939.

CREATE INDEXIf you create an index on a primary key, unique key, or ROWID columnthat is defined as GENERATED BY DEFAULT, the index will be treated asa regular index instead of an enforcing index.

CREATE AUXILIARY INDEXIf you issue a CREATE AUXILIARY INDEX statement and an auxiliaryindex that was implicitly created by DB2 already exists for the same basetable, the CREATE AUXILIARY INDEX statement fails and DB2 issuesSQLCODE -748, SQLCODE 54048, and reason code 3.

CREATEIf you issue a CREATE statement and do not specify an IN clause or tablespace name, and the default buffer pool is not large enough, DB2 chooses a4-KB, 8-KB, 16-KB, or 32-KB buffer pool, depending on the record size. Ifyou issue a CREATE statement and do not specify an IN clause or tablespace name, DB2 implicitly creates a partitioned-by-growth table space. Ifyou drop the table, DB2 also drops the containing table space.

DROP TABLEIf you issue a DROP TABLE statement to drop an auxiliary table from atable space that was implicitly created by DB2, the DROP TABLE statementfails and DB2 issues SQLCODE -20355, SQLSTATE 429BW, and reason code2.

DROP TABLESPACEIf you issue a DROP TABLESPACE statement to drop an implicitly-createdLOB table space, the DROP TABLESPACE statement fails and DB2 issuesSQLCODE -20355, SQLSTATE 429BW, and reason code 2.

DROP INDEXIf you issue a DROP INDEX statement to drop an enforcing primary key,unique key, or ROWID index from a table space that was implicitlycreated, the DROP INDEX statement fails and DB2 issues SQLCODE -669,SQLSTATE 42917, and reason code 2. If you issue a DROP INDEXstatement to drop an auxiliary index from a table space that was implicitlycreated, the DROP INDEX statement fails and DB2 issues SQLCODE-20355, SQLSTATE 429BW, and reason code 2.


||||||||||||||||||||||||||||||||||||||||||||||||

Changes to INSERT, UPDATE, or DELETE statements on someindexes

In Version 9.1, you cannot execute INSERT, UPDATE, or DELETE statements thataffect an index in the same commit scope as ALTER INDEX statements on thatindex.

LOBs with a maximum length greater than 1 GB can now belogged

In previous releases, only LOBs with a maximum length of 1 GB or less could belogged. In Version 9.1, LOBs with a maximum length that is greater than 1 GB canbe logged.

DB2 returns an error when a LOB value is specified for anargument to a stored procedure and the argument value islonger than the target parameter and the excess is not trailingblanks

In previous releases, DB2 did not return an error when a LOB value was specifiedfor an argument to a stored procedure and the argument value was longer than thetarget parameter and the excess was not trailing blanks. DB2 truncated the dataand the procedure executed. In Version 9.1, DB2 returns an error.

Changes to VARCHAR function formatting of decimal data

In Version 9.1, the formatting of decimal data has changed for the VARCHARfunction and CAST specification with a VARCHAR result type. When the inputdata is decimal, any leading zeroes in the input value are removed, and leadingzeroes are not added to an input value that did not already contain leading zeroes.

Changes to VARCHAR_FORMAT function length attribute

In Version 9.1, the length attribute of the result is the length attribute of the formatstring, up to a maximum of 100.

W is no longer recognized as a valid format element of theVARCHAR_FORMAT function format string

DB2 Version 9.1 no longer recognizes W as a valid format element of theVARCHAR_FORMAT function format string. Version 8 never recognized W as avalid format element

Use WW instead. Drop and recreate existing views and materialized queries thatare defined with Version 9.1 and that use the W format element with theVARCHAR_FORMAT function. Rebind existing bound statements that are boundwith Version 9.1 and that use the W format element with theVARCHAR_FORMAT function.

Leading or trailing blanks from the VARCHAR_FORMAT functionformat string are no longer removed

Leading or trailing blanks from the format string for the VARCHAR_FORMATfunction are no longer removed. Existing view definitions are recalculated as partof Version 9.1, so the new rules take effect. You can continue to use existingmaterialized query statements, but they use the old rules and remove leading and


||||||||||||||||||||||||||||||||||||||||||

trailing blanks. Existing references to the VARCHAR_FORMAT function in boundstatements only get the new behavior when they have been bound or rebound inVersion 9.1.

DB2 issues warnings when some BEFORE or AFTER triggers arecreated

DB2 Version 9.1 for z/OS issues a warning when a BEFORE or AFTER trigger iscreated and a trigger transition variable is passed as an argument for a parameteron a CALL statement that is within the trigger body.

DB2 drops certain indexes when a unique constraint is dropped

In previous releases, if a unique constraint was dropped, DB2 did not drop theindex that enforced uniqueness. In Version 9.1, if a table is in an implicitly-createdtable space, and a unique constraint on that table is dropped, DB2 drops the indexthat enforces uniqueness.

Changes to the upper limit to the size of the row that is used bysort to evaluate column functions

The maximum limit of a row (data and key columns) that is used by sort toevaluate MULTIPLE DISTINCT and GROUP BY column functions is decreased to32600. If you exceed the limit, DB2 issues an error.

DB2 enforces restriction on specifying a CAST FROM clause forsome forms of CREATE FUNCTION statements

The CAST FROM clause is included only in the syntax diagram for the CREATEFUNCTION statement for an external scalar function. The CAST FROM clause isnot included in the syntax diagrams for the other variations of CREATEFUNCTION (external table function, sourced function, or SQL function); the clausecannot be used for these other variations. In previous releases, if you specified aCAST FROM clause in an unsupported context, you received no errors. In Version9.1 if a CAST FROM clause is specified in an unsupported context, DB2 issues anerror.

DB2 enforces restrictions on specifying the AS LOCATOR clauseand TABLE LIKE clause

The AS LOCATOR clause for LOBs is included in the syntax diagram for theCREATE FUNCTION statement for an SQL function. This clause is not supportedin other contexts when identifying an existing SQL function such as in an ALTER,COMMENT, DROP, GRANT, or REVOKE statement. In previous releases, if youspecified an AS LOCATOR clause for LOBs in an unsupported context, you mightnot have received an error. In Version 9.1 if an AS LOCATOR clause for LOBs isspecified in an unsupported context, DB2 issues an error.

The TABLE LIKE clause for a trigger transition table is included only in the syntaxdiagram for the CREATE FUNCTION statement for an external scalar function,external table function, or sourced function. This clause is not supported for SQLfunctions or in other contexts when identifying an existing function such as in anALTER, COMMENT, DROP, GRANT, or REVOKE statement, or in the SOURCEclause of a CREATE FUNCTION statement. In previous releases, if you specified aTABLE LIKE clause for a trigger transition table in an unsupported context, youmight not have received an error. In Version 9.1 if a TABLE LIKE clause for a


|||||||||||||||||||||||||||||||||||||||||||||

trigger transition table is specified in an unsupported context, DB2 issues an error.

DB2 enforces restriction on the CCSID parameter for theDECRYPT_BIT and DECRYPT_BINARY functions

The CCSID parameter is not supported by the DECRYPT_BIT andDECRYPT_BINARY built-in functions. In previous releases, if you specified anargument for the CCSID parameter for these functions, you received no errors. InVersion 9.1 if an argument is specified for the CCSID parameter in an unsupportedcontext, DB2 issues an error.

Changed behavior of CREATE PROCEDURE for an SQLprocedure

With the introduction of native SQL procedures in Version 9.1, the semantics of theCREATE PROCEDURE statement for an SQL procedure has changed. Starting inVersion 9.1, all SQL procedures that are created without the FENCED option or theEXTERNAL option in the CREATE PROCEDURE statement are native SQLprocedures. In previous releases of DB2, if you did not specify either of theseoptions, the procedures were created as external SQL procedures.

If you do specify FENCED or EXTERNAL, the meanings are the same as inprevious releases of DB2. Both of these keywords mean that an external SQLprocedure is to be created.

Explicitly qualify names of variables, parameters, and columns inSQL procedures

In Version 9.1, the rules used for name resolution within a native SQL procedurediffer from the rules that were used for SQL procedures in prior releases. Becausean SQL parameter or SQL variable can have the same name as a column name,you should explicitly qualify the names of any SQL parameters, SQL variables orcolumns that have non-unique names. For more information about how the namesof these items are resolved, see the topic References to SQL parameters and SQLvariables. The rules used for name resolution within external SQL proceduresremains unchanged.

Make any necessary program changes for possibly differentvalues for RETURNED_SQLSTATE andDB2_RETURNED_SQLCODE

In Version 9.1, when an SQL statement other than GET DIAGNOSTICS orcompound-statement is processed, the current diagnostics area is cleared beforeDB2 processes the SQL statement. Clearing of the diagnostics area can result indifferent values being returned for RETURNED_SQLSTATE andDB2_RETURNED_SQLCODE for a GET DIAGNOSTICS statement than whatwould be returned if the GET DIAGNOSTICS statement were issued from withinan external SQL procedure. Additionally, there might be some differences in thevalues returned for the SQLSTATE and SQLCODE SQL variables than would havebeen returned from an external SQL procedure. (External SQL procedures werepreviously called SQL procedures in Version 8.)


||||||||||||||||||||||||||||||||||||||||||

SQLSTATE and SQLCODE SQL variables after a GETDIAGNOSTICS statement

In Version 9.1, the SQLSTATE and SQLCODE SQL variables are not clearedfollowing a GET DIAGNOSTICS statement.

Coding multiple SQL statements in a handler body

Previous releases of DB2 did not allow for a compound statement within a handler.A workaround to include multiple statements within a handler (without supportfor a compound statement in a handler) was to use another control statement, suchas an IF statement, which in turn contained multiple statements. Version 9.1 nowsupports a compound statement within a handler body. The compound statementis recommended for including multiple statements within a handler body.

Unhandled warnings

In Version 9.1, when a native SQL procedure completes processing with anunhandled warning, DB2 returns the unhandled warning to the calling application.The behavior of an external SQL procedure is unchanged from releases prior toVersion 9.1. When such a procedure completes processing with an unhandledwarning, DB2 does not return the unhandled warning to the calling application.

Change your programs to handle any changed messages fromSQL procedures

In Version 9.1, DB2 issues different messages for the new native SQL proceduresthan it does for external SQL procedures. (External SQL procedures werepreviously called SQL procedures in Version 8.) For external SQL procedures, DB2continues to issue DSNHxxxx messages. For native SQL procedures, DB2 issuesSQL return codes. The relationship between these messages is shown in thefollowing table:

Table 1. Relationship between DSNHxxxx messages that are issued for external SQLprocedures and SQLCODEs that are issued for native SQL proceduresDSNHxxxx message1 SQLCODE2

DSNH051I -051

DSNH385I +385

DSNH590I -590

DSNH4408I -408

DSNH4777I -777

DSNH4778I -778

DSNH4779I -779

DSNH4780I -780

DSNH4781I -781

DSNH4782I -782

DSNH4785I -785

DSNH4787I -787

Note:


||||||||||||||||||||||||||||||||||||||||||||||||||||||||

1. These messages are used for external SQL procedures, which can be defined byspecifying EXTERNAL or FENCED in Version 9.1.

2. These messages are used for native SQL procedures in Version 9.1.

Enhanced data type checking for zero-length characters

In Version 9.1, when you specify a CHAR data type with a length of 0 in theSQLDA, DB2 issues SQLCODE -804 regardless of the null indicator value.

Adding a column generates a new table space version

In previous releases, adding a column to a table did not generate a new table spaceversion. In Version 9.1, adding a column to a table with an ALTER TABLE ADDCOLUMN statement generates a new table space version.

You cannot add a column and issue SELECT, INSERT, UPDATE,DELETE, or MERGE statements in the same commit scope

You cannot have a version-generating ALTER TABLE ADD COLUMN statementand SELECT, INSERT, UPDATE, DELETE, or MERGE statements in the samecommit scope. If a version-generating ALTER TABLE ADD COLUMN statementfollows SELECT, INSERT, UPDATE, DELETE, or MERGE statements in the samecommit scope, SQLCODE -910 is issued. SQLCODE -910 is also issued if SELECT,INSERT, UPDATE, DELETE, or MERGE statements follow a version-generatingALTER TABLE ADD COLUMN statement in the same commit scope.

CAST FROM clause of CREATE FUNCTION statement for SQLfunctions is no longer supported

The CAST FROM clause of the CREATE FUNCTION statement for SQL functionsis no longer supported. If you issue a CREATE FUNCTION statement for an SQLfunction with a CAST FROM clause, DB2 issues an error.

GRAPHIC and NOGRAPHIC SQL processing options aredeprecated

If you specify the SQL processing options GRAPHIC or NOGRAPHIC, DB2 ignoresthem. These options are superseded by the CCSID SQL processing option.

Specifying ALTER DATABASE STOGROUP for work filedatabases

In previous releases of DB2, you could not execute ALTER DATABASESTOGROUP on a work file database. Beginning with DB2 Version 9.1 conversionmode, this restriction is removed.

DB2 enforces restrictions about where an INTO clause can bespecified

The INTO clause (as related to queries) is included only in the syntax diagram forthe SELECT INTO statement. The INTO clause is not included in the syntaxdiagrams for select-clause, subselect, fullselect, or select-statement. In previousreleases, if you specified an INTO clause in an unsupported context in a query, youmight not have received an error. In Version 9.1 if an INTO clause is specified inan unsupported context, DB2 issues an error.


|||||||||||||||||||||||||||||||||||||||||

Determining the value of any SQL processing options that affect thedesign of your program

When you process SQL statements in an application program, you can specifyoptions that describe the basic characteristics of the program or indicate how youwant the output listings to look. Although most of these options do not affect howyou design or code the program, a few options do.

SQL processing options specify program characteristics such as the following items:v The host language in which the program is writtenv The maximum precision of decimal numbers in the programv How many lines are on a page of the precompiler listingIn many cases, you may want to accept the default value provided.

To determine the value of any SQL processing options that affect the design ofyour program:

Review the list of SQL processing options and decide the values for any optionsthat affect the way that you write your program. For example, you need to know ifyou are using NOFOR or STDSQL(YES) before you begin coding.

Related concepts

DB2 program preparation overview on page 911Related reference

Descriptions of SQL processing options on page 868

Determining the binding methodBefore you can run an application, you must bind a plan. You can bind all of yourdatabase request modules (DBRMs) into a single application plan or you can firstbind packages and then bind those packages into a plan. The bind method thatyou choose can affect your application design.

You can choose one of the following binding methods:v Bind all of your DBRMs into a single application plan.v Bind all of your DBRMs into separate packages. Then bind all those packagesinto a single application plan.

v Bind some of your DBRMs into separate packages. Then bind those packagesand any other DBRMs for that program into an application plan.

The use of packages affects your application design. For example, you mightdecide to put certain SQL statements together in the same program, precompilethem into the same DBRM, and then bind them into a single package.

To determine the binding method:

Consider the advantages and disadvantages of each binding method, which aredescribed in the following table.


|||||||||||||||||||||||||||||||||||||||

Table 2. Advantages and disadvantages of each binding methodBinding method Advantages Disadvantages

Bind all of your DBRMsinto a single applicationplan.

This method has fewer steps and is appropriate insome cases. This method is suitable for smallapplications that are unlikely to change or that requireall resources to be acquired when the plan is allocated,rather than when your program first uses them.

Maintenance is difficult. Thismethod has the disadvantagethat a change to one DBRMrequires rebinding the entireplan, even though most DBRMsare unchanged.


|||||||||||||

||||||

Table 2. Advantages and disadvantages of each binding method (continued)Binding method Advantages Disadvantages

Bind all of your DBRMsinto separate packages.Then bind all thosepackages into a singleapplication plan

Maintenance is easier. When you use packages, you donot need to bind the entire plan again when youchange one SQL statement. You need to bind only thepackage that is associated with the changed SQLstatement.

You can incrementally develop your program withoutrebinding the plan. A collection is a group of associatedpackages. Binding packages into package collectionsenables you to add packages to an existing applicationplan without having to bind the plan again. If youinclude a collection name in the package list when youbind a plan, any package in the collection becomesavailable to the plan. The collection can be empty whenyou first bind the plan. Later, you can add packages tothe collection and drop or replace existing packageswithout binding the plan again.

You can maintain several versions of a package withinthe same plan. Maintaining several versions of a planwithout using packages requires a separate plan foreach version, and therefore, separate plan names andRUN commands. Isolating separate versions of aprogram into packages requires only one plan andhelps to simplify program migration and fallback. Forexample, you can maintain separate development, test,and production levels of a program by binding eachlevel of the program as a separate version of a package,all within a single plan. You cannot bind or rebind apackage or a plan while it is running. However, youcan bind a different version of a package that isrunning.

You can use different bind options for differentDBRMs. The options of the BIND PLAN commandapply to all DBRMs that are bound directly to the plan.The options of the BIND PACKAGE command apply toonly the single DBRM that is bou

db2 v9 application programming&sql guide dsnapk13

Documents

caf trace69caf

examples of invoking

program recovery

rrsaf connection functions

summary of rrsaf behavior

summary of caf behavior

caf connection functions

sample rrsaf scenarios