DB2 UDB for AS/400 Object Relational Support Jarek Miszczyk, Bronach Bromley, Mark Endrei Skip Marchesani, Deepak Pai, Barry Thorn International Technical Support Organization www.redbooks.ibm.com SG24-5409-00 International Technical Support Organization SG24-5409-00 DB2 UDB for AS/400 Object Relational Support February 2000 Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix B, “Special notices” on page 229. First Edition (February 2000) This edition applies to Version 4 Release 4 of the Operating System/400 (5769-SS1). Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. JLU Building 107-2 3605 Highway 52N Rochester, Minnesota 55901-7829 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright International Business Machines Corporation 2000. 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. Contents Figures ......................................................vii Preface ......................................................xi The team that wrote this redbook .......................................xi Commentswelcome................................................ xii Chapter 1. Introduction..........................................1 1.1 Why we need complex objects on an AS/400 system .................1 1.2Usingcomplexobjects........................................2 Chapter 2. Large object support in DB2 UDB for AS/400 ...............3 2.1 A need for large objects .......................................3 2.2WhatisanLOB?.............................................4 2.3UsingLOBswithSQL.........................................5 2.3.1CreatingatablewithLOBdatatypes.........................5 2.3.2 Adding data to the CUSTOMERHUS table . ..................7 2.4LOBlocators................................................8 2.4.1LOBlocatorcharacteristics.................................8 2.4.2LOBlocatorprocessing....................................9 2.4.3CommitmentcontrolandLOBlocators.......................12 2.5LOBfilereferencevariable....................................12 2.5.1LOBfilereferencecharacteristics...........................13 2.5.2LOBfilereferenceprocessing..............................14 2.6CommitmentcontrolandjournalingforLOBs......................18 2.7 SQL functions supporting LOBs ................................19 2.7.1 Basic predicate support for LOBs ...........................19 2.7.2Columnfunctions.......................................21 2.7.3Scalarfunctions........................................21 2.8LOBsandthenativeinterface..................................22 2.9LOBcolumnconsiderations...................................24 2.9.1 Triggers. ............................................25 2.9.2UsinginNet.Data.......................................25 Chapter 3. User-defined Distinct Types (UDTs)......................27 3.1 A need for user-defined types . .................................27 3.2Creatingdistincttypes........................................28 3.2.1CreatingUDTsourcedfromDECIMAL.......................28 3.2.2CreatingatableusingUDTs...............................29 3.2.3CreatingdistincttypeswiththeSQLinterface..................32 3.2.4Alteringanddeletingdistincttypes..........................34 3.3Castingfordistincttypes......................................34 3.3.1Explicitcasting.........................................35 3.3.2Implicitcasting.........................................38 3.3.3Implicitcastingandpromotion..............................40 3.3.4Implicitcastingandhostvariables...........................42 3.4 SQL support for distinct types . .................................43 3.4.1UsingpredicateswithUDT................................44 3.4.2JoiningonUDT.........................................45 3.4.3UsingadefaultvaluewithUDT.............................47 3.5DB2UDBforAS/400implementation............................49 3.5.1Nativesysteminterfaces..................................49 iii 3.5.2 Keeping track of distinct types ............................. 57 3.5.3 Database recovery. .................................... 62 Chapter 4. User Defined Functions (UDFs) ........................ 69 4.1 A need for User Defined Functions ............................. 69 4.2UDFtypes................................................ 70 4.2.1Sourced.............................................. 70 4.2.2SQL................................................. 70 4.2.3External.............................................. 71 4.3ResolvingUDF............................................71 4.3.1 UDF function overloading and function signature . .............. 72 4.3.2Functionpathandthefunctionselectionalgorithm..............72 4.3.3Parametermatchingandpromotion.........................74 4.3.4Thefunctionselectionalgorithm...........................76 4.4CodingUDFs.............................................. 77 4.4.1CodingsourcedUDFs................................... 78 4.4.2CodingSQLUDFs...................................... 85 4.4.3CodingexternalUDFs................................... 95 4.5FunctionresolutionandparameterpromotioninUDFs............. 108 4.5.1AnexampleoffunctionresolutioninUDFs................... 108 4.5.2AnexampleofparameterpromotioninUDF................. 112 4.6ThesystemcatalogforUDFs................................ 116 4.6.1SYSROUTINEScatalog................................. 116 4.6.2SYSPARMScatalog................................... 117 4.7 Dropping UDFs . ........................................ 118 4.8SavingandrestoringUDFs.................................. 119 4.9 Debugging UDFs . ........................................ 119 4.10Codingconsiderations..................................... 127 Chapter 5. Programming alternatives for complex objects........... 129 5.1UsingcomplexobjectsinJavaclientapplications................. 129 5.1.1 Getting ready to use JDBC 2.0 driver....................... 129 5.1.2UsingaBlobobject.................................... 130 5.1.3UsingaClobobject.................................... 134 5.1.4 Using metadata ....................................... 137 5.2UsingcomplexobjectsinCLIorODBC......................... 139 5.2.1DB2CLIapplicationflow................................ 139 5.2.2 Passing LOB to a stored procedure written in CLI ............. 139 5.2.3 Calling the CLI stored procedure . ........................ 143 5.2.4RetrievingLOBsinCLI................................. 143 Chapter 6. DataLinks ......................................... 147 6.1 A need for DataLinks ....................................... 147 6.2 DataLinks components . ................................... 150 6.2.1DataLinkdatatype..................................... 150 6.2.2 DataLink file manager .................................. 151 6.2.3DataLinkfilter........................................ 153 6.2.4APIs................................................ 153 6.3DataLinkssystemconfiguration............................... 154 6.3.1InitializingtheDLFMserver.............................. 156 6.3.2DLFMconfiguration.................................... 157 6.3.3StartingtheDLFMserver................................ 163 6.4UsingDataLinkswithSQL................................... 164 6.4.1 DataLink options: General . ............................. 165 iv DB2 UDB for AS/400 Object Relational Support 6.4.2 DataLink options: DB2 Universal Database for AS/400 ..........167 6.4.3Datamanipulationexamples..............................178 6.4.4DataLinkSQLscalarfunctions............................182 6.4.5 Using the DataLink in dynamic Web pages . ................183 6.4.6UsingtheDataLinkaccesscontroltoken.....................186 6.5Nativeinterfaceconsiderations................................193 6.6 DataLinks management considerations..........................202 6.6.1 Backup and recovery procedures ..........................202 6.7 Using DataLinks in a heterogeneous environment. ................212 6.7.1 DataLinks Manager for Windows NT and for AIX...............212 Appendix A. Source code listings .................................215 A.1 UDTLABA: Using UDTs . .......................................215 A.2 UDTLABB: Casting UDTs .......................................216 A.3PictCheck:ExternalUDF........................................218 A.4ChkHdr.....................................................220 A.5RunGetPicture:TestingGetPictureUDF............................220 A.6Rating:ExternalUDFusingSCRATCHPAD.........................221 A.7 RtvPrdNbr3: External stored procedure written in CLI .................222 Appendix B. Special notices......................................229 Appendix C. Related publications .................................231 C.1 IBM Redbooks publications......................................231 C.2 IBM Redbooks collections.......................................231 C.3Otherresources..............................................231 C.4ReferencedWebsites..........................................232 How to get IBM Redbooks ......................................233 IBM Redbooks fax order form. .......................................234 List of abbreviations ..........................................235 Index .......................................................237 IBM Redbooks evaluation