ibm.com/redbooks Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries Hernando Bedoya Fredy Cruz Daniel Lema Satid Singkorapoom Develop robust DB2 Universal Database for iSeries applications Discover the details of SQL stored procedures and SQL triggers Learn the secrets of user-defined functions International Technical Support Organization Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries October 2006 SG24-6503-02 © Copyright International Business Machines Corporation 2001, 2004, 2006. All rights reserved. Note to U.S Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Third Edition (October 2006) This edition applies to V5R1, V5R2, and V5R3 of IBM OS/400 and V5R4 of IBM i5/OS, Program Number 5722-SS1. Take Note! Before using this information and the product it supports, be sure to read the general information in “Notices” on page xi. iii Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi Part 1. Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Introducing DB2 Universal Database for iSeries . . . . . . . . . . . . . . . . . . . . . . 3 1.1 An integrated relational database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 DB2 Universal Database for iSeries: An overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.1 DB2 Universal Database for iSeries basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2.2 Stored procedures, triggers, and user-defined functions . . . . . . . . . . . . . . . . . . . . 6 1.3 DB2 Universal Database for iSeries sample schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Chapter 2. Stored procedures, triggers, and user-defined functions: Order entry application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.1 Order Entry application overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2 Order Entry database overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.3 Stored procedures and triggers in the Order Entry database . . . . . . . . . . . . . . . . . . . . 17 2.3.1 Stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.3.2 Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.3.3 User-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Chapter 3. Introduction to the SQL Persistent Stored Module in DB2 Universal Database for iSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 3.2 System requirements and planning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 3.3 Structure of a SQL PSM program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.4 SQL control statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.4.1 Assignment statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.4.2 Conditional control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 3.4.3 Iterative control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.4.4 Calling procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 3.5 Compound SQL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 3.5.1 Nested compound statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 3.5.2 Variable declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 3.5.3 Using cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.6 Using scrollable cursors in SQL PSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 3.7 Dynamic SQL in SQL PSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 3.7.1 PREPARE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 3.7.2 EXECUTE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.7.3 EXECUTE IMMEDIATE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.7.4 Cursors based on dynamic SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.8 Moving into production (save and restore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.8.1 Restore processing for V4R5 and prior releases . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.8.2 Restore processing for V5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 iv Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries 3.9 Adopted authorities in SQL PSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3.9.1 Authorities and adopted authorities in dynamic SQL . . . . . . . . . . . . . . . . . . . . . . 38 3.10 Testing and debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.10.1 Graphical debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.10.2 The ILE source debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3.10.3 Preparing the SQL procedure for debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 3.10.4 Testing the SQL PSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 3.10.5 Testing the SQL PSM in a distributed environment . . . . . . . . . . . . . . . . . . . . . . 52 3.11 Reverse engineering and Generate SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 3.11.1 Generate SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Part 2. Stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Chapter 4. Stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 4.2 Stored procedure types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.2.1 SQL stored procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.2.2 External stored procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.3 Registering stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.3.1 CREATE PROCEDURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.3.2 DECLARE PROCEDURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 4.4 System catalog tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 4.4.1 SYSROUTINES catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 4.4.2 SYSPARMS catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 4.5 Procedure signature and procedure overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 4.6 Deleting or replacing a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.6.1 Using a command line to drop a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.6.2 Dropping overloaded procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 4.7 Authorization and adopted authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 4.8 Returning result sets from stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Chapter 5. SQL stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 5.2 Structure of an SQL stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 5.2.1 Example of a single SQL statement stored procedure . . . . . . . . . . . . . . . . . . . . . 83 5.2.2 Example of a compound SQL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 5.3 Creating an SQL stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 5.3.1 Creating an SQL stored procedure with iSeries Navigator . . . . . . . . . . . . . . . . . . 85 5.3.2 Creating an SQL stored procedure with the Run SQL Scripts utility. . . . . . . . . . . 88 5.3.3 Creating an SQL stored procedure with DB2 Universal Database Development Center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 5.3.4 Creating an SQL stored procedure with traditional 5250 tools . . . . . . . . . . . . . . . 98 5.3.5 Verifying the stored procedure properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 5.4 System catalog tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 5.5 SQL procedures returning result sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 5.5.1 Creating result sets in an SQL stored procedure . . . . . . . . . . . . . . . . . . . . . . . . 103 5.5.2 Retrieving result sets in the caller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 5.5.3 Using ADO in the Visual Basic client to retrieve result sets . . . . . . . . . . . . . . . . 104 5.6 Global Temporary Table: A result set alternative . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 5.6.1 Purpose of a Global Temporary Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 5.6.2 Storing a result set into a Global Temporary Table. . . . . . . . . . . . . . . . . . . . . . . 107 5.6.3 Accessing a result set from a Global Temporary Table . . . . . . . . . . . . . . . . . . . 110 5.7 GetSuppliers example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 5.7.1 Creating the SQL stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 v 5.7.2 Displaying the result sets with iSeries Navigator . . . . . . . . . . . . . . . . . . . . . . . . 114 5.7.3 Calling an SQL procedure from the Visual Basic client application . . . . . . . . . . 115 5.8 Implicit object qualification and authorization resolution . . . . . . . . . . . . . . . . . . . . . . . 117 5.8.1 Implicit schema qualification for static and dynamic SQL in procedures . . . . . . 117 5.8.2 Dynamic resolution of authorization ID at runtime . . . . . . . . . . . . . . . . . . . . . . . 121 Chapter 6. External stored procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 6.1 Registering external stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 6.1.1 Registering an external procedure with iSeries Navigator . . . . . . . . . . . . . . . . . 124 6.2 Parameter styles in external stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 6.2.1 SQL parameter style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 6.2.2 DB2SQL parameter style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 6.2.3 GENERAL WITH NULLS parameter style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 6.2.4 GENERAL parameter style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 6.3 Coding external stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 6.3.1 Coding for SQL parameter style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 6.3.2 Coding the DB2SQL parameter style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 6.3.3 Coding the GENERAL WITH NULLS parameter style . . . . . . . . . . . . . . . . . . . . 140 6.4 Returning result sets from external procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 6.4.1 Coding external stored procedures returning cursor result sets . . . . . . . . . . . . . 144 6.4.2 Coding external stored procedures returning array result sets . . . . . . . . . . . . . . 150 6.5 CLI client program that calls a procedure that returns multiple result sets . . . . . . . . . 151 6.6 Moving into production (save and restore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 6.7 The Order Entry application: Stored procedures examples . . . . . . . . . . . . . . . . . . . . 157 6.7.1 Calling a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 6.7.2 Sample stored procedure: SQL RPG version . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 6.8 External stored procedure using service program . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 6.9 RPG IV example for external stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 6.9.1 External stored procedure that writes to a data queue . . . . . . . . . . . . . . . . . . . . 170 6.9.2 External stored procedure that reads from a data queue . . . . . . . . . . . . . . . . . . 171 6.9.3 Calling external stored procedures from Run SQL Scripts utility . . . . . . . . . . . . 172 Chapter 7. Java stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 7.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 7.2 Coding DB2 Universal Database for iSeries Java stored procedures. . . . . . . . . . . . . 174 7.2.1 Parameter styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 7.2.2 Data type compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 7.2.3 Database connection in a Java stored procedure. . . . . . . . . . . . . . . . . . . . . . . . 177 7.2.4 Returning result sets in Java stored procedures. . . . . . . . . . . . . . . . . . . . . . . . . 178 7.3 Coding examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 7.3.1 Compilation of Java code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 7.3.2 Where to place Java classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 7.3.3 Creating Java programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 7.4 Registering Java stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 7.4.1 Registering Java stored procedures with iSeries Navigator . . . . . . . . . . . . . . . . 189 7.4.2 Using the Run SQL Scripts utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 7.4.3 Using the native interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 7.5 Calling Java stored procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 7.6 Using SQL NULL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 7.7 SQLJ procedures to manipulate JAR files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 7.7.1 SQLJ.INSTALL_JAR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 7.7.2 SQLJ.REMOVE_JAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 7.7.3 SQLJ.REPLACE_JAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 vi Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries 7.7.4 SQLJ.UPDATEJARINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 7.7.5 SQLJ.RECOVERJAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 7.8 Additional considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 7.8.1 Moving into production (save and restore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 7.9 GetSuppliers example: Implementation with no result sets. . . . . . . . . . . . . . . . . . . . . 204 7.9.1 Stored procedure: GetSupplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 7.9.2 Java client: ClientGetSupplier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 7.9.3 Java GUI client: ClientGetSupplierGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 7.10 GetSuppliers example: Implementation with result sets . . . . . . . . . . . . . . . . . . . . . . 211 7.10.1 GetSuppliers stored procedure with the Java parameter style . . . . . . . . . . . . . 211 7.10.2 GetSuppliers stored procedure with the DB2GENERAL parameter style. . . . . 214 7.10.3 Java clients: ClientGetSupplier and ClientGetSupplierGUI. . . . . . . . . . . . . . . . 216 7.11 Problem determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 7.11.1 Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 7.11.2 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Chapter 8. Stored procedure error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 8.1 Database error reporting strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 8.1.1 User-defined errors and warnings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 8.1.2 Consistent error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 8.2 Error handling in SQL stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 8.2.1 Condition and handler declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 8.2.2 SIGNAL and RESIGNAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 8.2.3 SQLCODE and SQLSTATE variable in the SQL procedure. . . . . . . . . . . . . . . . 231 8.2.4 Returning values using the RETURN statement. . . . . . . . . . . . . . . . . . . . . . . . . 231 8.2.5 GET DIAGNOSTICS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 8.2.6 Error handling in nested compound statements . . . . . . . . . . . . . . . . . . . . . . . . . 234 8.2.7 Use nested compound statements for better performance. . . . . . . . . . . . . . . . . 241 8.3 Error handling in external stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 8.3.1 Checking the stored procedure completion status . . . . . . . . . . . . . . . . . . . . . . . 242 8.3.2 GENERAL and GENERAL WITH NULLS parameter styles . . . . . . . . . . . . . . . . 246 8.4 Error handling in Java stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 8.5 Retrieving user-defined errors in a client application . . . . . . . . . . . . . . . . . . . . . . . . . 250 8.5.1 Retrieving error conditions in a JDBC client . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 8.5.2 Retrieving error conditions from an ODBC or CLI client . . . . . . . . . . . . . . . . . . . 253 8.6 Transaction management in stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 8.6.1 Transaction management terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 8.6.2 Transactional behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 8.6.3 SQL statements for controlling transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 8.6.4 Transaction management in compound statements . . . . . . . . . . . . . . . . . . . . . . 261 8.7 External stored procedures and commitment control . . . . . . . . . . . . . . . . . . . . . . . . . 263 8.7.1 Activation group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 8.7.2 Savepoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 8.8 Some practical examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 8.8.1 SQL stored procedure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 8.8.2 External stored procedure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 8.8.3 Java stored procedure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 8.8.4 C++ client code using ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 8.8.5 Java example client code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 8.8.6 Results for the example programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Part 3. Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Chapter 9. Database triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 vii 9.1 Trigger concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 9.2 Types of triggers in DB2 Universal Database for iSeries . . . . . . . . . . . . . . . . . . . . . . 284 9.2.1 SQL triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 9.2.2 External triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 9.3 Enabling and disabling a trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 9.4 Displaying and reviewing trigger information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 9.4.1 Using iSeries Navigator to view the properties of a trigger . . . . . . . . . . . . . . . . . 286 9.4.2 Displaying trigger information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 9.4.3 Printing trigger information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 9.5 System catalog tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 9.6 Authorization and adopted authorities on triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 9.7 Renaming and copying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Chapter 10. SQL triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 10.1 Introduction to SQL triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 10.2 System requirements and planning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 10.3 Structure of an SQL trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 10.3.1 Components of the SQL trigger definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 10.3.2 Simple SQL trigger example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 10.3.3 Example of a trigger program using WHEN condition. . . . . . . . . . . . . . . . . . . . 300 10.4 Creating an SQL trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 10.4.1 Creating an SQL trigger with iSeries Navigator . . . . . . . . . . . . . . . . . . . . . . . . 301 10.4.2 Creating an SQL trigger with the Run SQL Scripts utility . . . . . . . . . . . . . . . . . 308 10.4.3 Creating SQL triggers with traditional interfaces. . . . . . . . . . . . . . . . . . . . . . . . 312 10.4.4 Verifying the SQL trigger properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 10.5 Deleting or replacing an SQL trigger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 10.6 Trigger component details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 10.6.1 Trigger time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 10.6.2 Trigger modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 10.6.3 Trigger granularity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 10.7 Accessing triggering data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 10.7.1 Correlation variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 10.7.2 Transition tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 10.7.3 Changing values in the firing row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 10.8 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 10.8.1 Signaling errors from a trigger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 10.8.2 Recovering errors fired by triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 10.9 Inoperative triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 10.10 Moving into production (save and restore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 10.11 Resolution of unqualified object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 10.12 Transaction isolation and recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 10.12.1 Savepoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 10.12.2 ATOMIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 10.13 Additional considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 10.13.1 Adding columns to a subject table referenced in the triggered action. . . . . . . 342 10.13.2 Datetime considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 10.13.3 SQL trigger program object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 10.13.4 Authority of SQL triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 10.14 Testing and debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 10.14.1 The ILE source debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 10.14.2 Preparing the SQL trigger for debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 10.14.3 Testing the SQL trigger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 10.14.4 Testing the SQL trigger in a client/server environment. . . . . . . . . . . . . . . . . . 347 viii Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries 10.15 SQL trigger examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 10.15.1 Self-referencing triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 10.15.2 SQL trigger invoking external programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 10.15.3 SQL trigger invoking Java stored procedures or UDFs. . . . . . . . . . . . . . . . . . 352 10.15.4 Accessing a Global Temporary Table from an SQL trigger . . . . . . . . . . . . . . 354 10.15.5 Instead Of Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 Chapter 11. External triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 11.1 Defining a trigger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 11.1.1 ADDPFTRG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 11.1.2 Using iSeries Navigator to add an external trigger . . . . . . . . . . . . . . . . . . . . . . 362 11.2 Trigger program structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 11.2.1 Trigger buffer for RPG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 11.2.2 Trigger buffer for COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 11.2.3 Trigger buffer for C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 11.2.4 Using the trigger buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 11.3 Trigger feedback to application programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 11.3.1 Commitment control and triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 11.4 Designing trigger programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 11.4.1 Order Entry application scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 11.4.2 Audit trail trigger example programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 11.4.3 Updating a trigger on the Order Header file program examples . . . . . . . . . . . . 397 11.4.4 Soft coding the trigger buffer example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 11.4.5 Changing the record that fired a trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 11.5 Applications and triggers: Design considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 11.6 Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 Chapter 12. Triggers, referential integrity, and constraints. . . . . . . . . . . . . . . . . . . . . 437 12.1 Transaction isolation and recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 12.2 Trigger journal entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 12.3 Triggers and referential integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 12.4 Comparing referential integrity and triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 12.4.1 Using triggers to implement referential integrity rules. . . . . . . . . . . . . . . . . . . . 439 12.5 Constraints and triggers: Ordering the actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 12.5.1 Insert operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 12.5.2 Update operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 12.5.3 Delete operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 12.6 Triggers, referential integrity, and commitment control . . . . . . . . . . . . . . . . . . . . . . . 444 12.6.1 When the application is not running commitment control . . . . . . . . . . . . . . . . . 444 12.6.2 When the application runs under commitment control . . . . . . . . . . . . . . . . . . . 444 12.7 Referential integrity, triggers, and journal entries . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 Part 4. User-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Chapter 13. User-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 13.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 13.2 Nature of user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 13.2.1 User-defined scalar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 13.2.2 User-defined table functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 13.3 Type of user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 13.3.1 Sourced UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 13.3.2 SQL UDFs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 13.3.3 External UDFs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 13.4 Creating user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 [...]... validation and audit trail creation DB2 Universal Database for iSeries supports two types of triggers: SQL triggers External triggers 6 Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries User-defined functions and user-defined table functions UDFs and user-defined table functions (UDTFs) are user-written programs that enrich the functionality of the database. .. xii Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries Preface Stored procedures, triggers, and user-defined functions (UDFs) are the key database features for developing robust and distributed applications DB2 Universal Database for iSeries has supported these features for many years, and they have been enhanced in V5R1, V5R2, and V5R3 of IBM® OS/400® and. .. in future DB2 Universal Database for iSeries documentation 8 Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries As a group, the tables include information that describes employees, departments, projects, and activities This information makes up a sample database demonstrating some of the features of DB2 Universal Database for iSeries An entity-relationship (ER)... the DB2 Universal Database for iSeries with a dramatic set of new functions As a result of these enhancements, the iSeries server has become one of the most functionally rich relational platforms in the industry DB2 Universal Database for iSeries is a member of the DB2 Universal Database family of products, which includes DB2 Universal Database for OS/390 and DB2 Universal Database The DB2 Universal Database. .. Triggers, and User-Defined Functions on DB2 Universal Database for iSeries 2 Chapter 2 Stored procedures, triggers, and user-defined functions: Order entry application This chapter describes how a simple Order Entry application can take advantage of the stored procedures, triggers and user-defined functions (UDFs) support available with DB2 Universal Database for iSeries It describes the complete application,... Universal Database for iSeries has changed to DB2 for i5/OS Considering the previous editions of this book and the minimal changes in this update, we have chosen to continue using the name DB2 Universal Database for iSeries in this edition © Copyright IBM Corp 2001, 2004, 2006 1 2 Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries 1 Chapter 1 Introducing DB2 Universal. .. functions that are mentioned in this section in several IBM manuals, for example: Database Programming, SC41-5701 SQL Reference, SC41-5612 4 Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries 1.2.1 DB2 Universal Database for iSeries basics As previously mentioned, the major distinguishing characteristic of the DB2 Universal Database for iSeries database manager is... Corporation, International Technical Support Organization Dept HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400 xvi Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries Part 1 Part 1 Background This part introduces the basics concepts of DB2 Universal Database for iSeries It describes the Order Entry application used to illustrate the use of stored. .. 565 x Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal Database for iSeries Notices This information was developed for products and services offered in the U.S.A IBM may not offer the products, services, or features discussed in this document in other countries Consult your local IBM representative for information on the products and services currently available... and triggers Plus, it explains the sample database provided in DB2 Universal Database for iSeries in V5R1 that will be used as well for illustrating stored procedures, triggers and user-defined functions We also dedicate one chapter to introduce the SQL Persistent Stored Module Language used in SQL stored procedures, triggers and functions Note: With the release of IBM i5/OS V5R4, the name of DB2 Universal . to continue using the name DB2 Universal Database for iSeries in this edition. xiv Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal. to continue using the name DB2 Universal Database for iSeries in this edition. 2 Stored Procedures, Triggers, and User-Defined Functions on DB2 Universal