AS/400e series

DB2 for AS/400 Database Programming

V ersion 4

SC41-5701-02

AS/400e series

DB2 for AS/400 Database Programming

V ersion 4

SC41-5701-02

Note Before using this information and the product it supports, be sure to read the information in Notices on page 401.

Third Edition (September 1998) This edition applies to version 4 release 3 modication 0 of Operating System/400 (product number 5769-SS1) and to all subsequent releases and modications until otherwise indicated in new editions. This edition replaces SC41-5701-01. This edition applies only to reduced instruction set computer (RISC) systems. Copyright International Business Machines Corporation 1997, 1998. 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 . . . . . . . . . . . . . . About DB2 for AS/400 Database Programming (SC41-5701) . . . . . .
Who should read this book. . . . . . . . . AS/400 Operations Navigator . . . . . . . . Installing Operations Navigator subcomponents Accessing AS/400 Operations Navigator . . . Prerequisite and related information. . . . . . How to send your comments . . . . . . . .

ix

Chapter 2. Setting Up Physical Files

Creating a Physical File. . . . . . . . . Specifying Physical File and Member Attributes Expiration Date . . . . . . . . . . Size of the Physical File Member . . . . Storage Allocation . . . . . . . . . Method of Allocating Storage . . . . . . Record Length . . . . . . . . . . . Deleted Records . . . . . . . . . . Physical File Capabilities . . . . . . . Source Type . . . . . . . . . . . . . . . . . . . .

35
35 35 35 36 36 36 37 37 38 38

xi
xi xi xii xii xiii xiii

Part 1. Setting Up Database Files

Chapter 1. General Considerations . .
Describing Database Files . . . . . . . . . Dictionary-Described Data . . . . . . . . Methods of Describing Data to the System . . Describing a Database File to the System. . . Describing Database Files Using DDS . . . . Describing the Access Path for the File . . . Protecting and Monitoring Your Database Data Database File Creation: Introduction . . . . . Database File and Member Attributes: Introduction File Name and Member Name (FILE and MBR) Parameters . . . . . . . . . . . . . Physical File Member Control (DTAMBRS) Parameter . . . . . . . . . . . . . . Source File and Source Member (SRCFILE and SRCMBR) Parameters . . . . . . . . . Database File Type (FILETYPE) Parameter Maximum Number of Members Allowed (MAXMBRS) Parameter. . . . . . . . . Where to Store the Data (UNIT) Parameter Frequency of Writing Data to Auxiliary Storage (FRCRATIO) Parameter. . . . . . . . . Frequency of Writing the Access Path (FRCACCPTH) Parameter . . . . . . . . Check for Record Format Description Changes (LVLCHK) Parameter . . . . . . . . . Current Access Path Maintenance (MAINT) Parameter . . . . . . . . . . . . . Access Path Recovery (RECOVER) Parameter File Sharing (SHARE) Parameter . . . . . Locked File or Record Wait Time (WAITFILE and WAITRCD) Parameters . . . . . . . Public Authority (AUT) Parameter . . . . . System on Which the File Is Created (SYSTEM) Parameter . . . . . . . . . . . . . File and Member Text (TEXT) Parameter . . . Coded Character Set Identier (CCSID) Parameter . . . . . . . . . . . . . Sort Sequence (SRTSEQ) Parameter . . . . Language Identier (LANGID) Parameter . . .

1
3
3 4 5 6 7 17 26 26 27 27 27 27 27 27 28 28 29 29 29 31 32 32 32 32 32 32 33 33

Chapter 3. Setting Up Logical Files . . 39

Describing Logical File Record Formats . . . . Describing Field Use for Logical Files . . . . Deriving New Fields from Existing Fields . . . Describing Floating-Point Fields in Logical Files Describing Access Paths for Logical Files . . . . Selecting and Omitting Records Using Logical Files . . . . . . . . . . . . . . . Using Existing Access Paths . . . . . . . Creating a Logical File . . . . . . . . . . Creating a Logical File with More Than One Record Format. . . . . . . . . . . . Logical File Members . . . . . . . . . Join Logical File Considerations . . . . . . . Basic Concepts of Joining Two Physical Files (Example 1) . . . . . . . . . . . . Setting Up a Join Logical File . . . . . . . Using More Than One Field to Join Files (Example 2) . . . . . . . . . . . . Reading Duplicate Records in Secondary Files (Example 3) . . . . . . . . . . . . Using Join Fields Whose Attributes Are Different (Example 4) . . . . . . . . . . . . Describing Fields That Never Appear in the Record Format (Example 5) . . . . . . . Specifying Key Fields in Join Logical Files (Example 6) . . . . . . . . . . . . Specifying Select/Omit Statements in Join Logical Files . . . . . . . . . . . . Joining Three or More Physical Files (Example 7) . . . . . . . . . . . . . . . . Joining a Physical File to Itself (Example 8) Using Default Data for Missing Records from Secondary Files (Example 9) . . . . . . . A Complex Join Logical File (Example 10) . . Performance Considerations . . . . . . . Data Integrity Considerations . . . . . . . Summary of Rules for Join Logical Files . . . 39 41 42 45 45 46 51 53 54 58 61 61 70 71 72 74 75 77 78 78 80 81 83 85 85 85

Chapter 4. Database Security . . . . . 89

File and Data Authority . . . . Object Operational Authority . Object Existence Authority . . . . . . . . . . . . . . . . . . . . 89 89 89

Copyright IBM Corp. 1997, 1998

iii

Object Management Authority . . Object Alter Authority . . . . Object Reference Authority . . Data Authorities . . . . . . Public Authority . . . . . . . Database File Capabilities . . . . Limiting Access to Specic Fields of a File . . . . . . . . . . . Using Logical Files to Secure Data .

. . . . . . . . . . . . . . . . . . . . . . . . Database . . . . . . . .

. . . . . . . .

89 90 90 90 91 92 92 93

Part 2. Processing Database Files in Programs. . . . . . . . . . . . 95

Chapter 5. Run Time Considerations
File and Member Name . . . . . . . . . . File Processing Options. . . . . . . . . . Specifying the Type of Processing . . . . . Specifying the Initial File Position . . . . . Reusing Deleted Records . . . . . . . . Ignoring the Keyed Sequence Access Path Delaying End of File Processing . . . . . . Specifying the Record Length . . . . . . . Ignoring Record Formats . . . . . . . . Determining If Duplicate Keys Exist . . . . . Data Recovery and Integrity . . . . . . . . Protecting Your File with the Journaling and Commitment Control . . . . . . . . . . Writing Data and Access Paths to Auxiliary Storage . . . . . . . . . . . . . . Checking Changes to the Record Format Description . . . . . . . . . . . . . Checking for the Expiration Date of the File Preventing the Job from Changing Data in the File . . . . . . . . . . . . . . . Sharing Database Files Across Jobs . . . . . Record Locks . . . . . . . . . . . . File Locks . . . . . . . . . . . . . Member Locks . . . . . . . . . . . . Record Format Data Locks . . . . . . . Sharing Database Files in the Same Job or Activation Group . . . . . . . . . . . . Open Considerations for Files Shared in a Job or Activation Group . . . . . . . . . . Input/Output Considerations for Files Shared in a Job or Activation Group . . . . . . . . Close Considerations for Files Shared in a Job or Activation Group . . . . . . . . . . Sequential-Only Processing . . . . . . . . Open Considerations for Sequential-Only Processing . . . . . . . . . . . . . Input/Output Considerations for Sequential-Only Processing . . . . . . . . . . . . . Close Considerations for Sequential-Only Processing . . . . . . . . . . . . . Run Time Summary . . . . . . . . . . . Storage Pool Paging Option Effect on Database Performance . . . . . . . . . . . . .

97
98 98 98 99 99 100 100 100 101 101 101 101 102 102 102 102 102 103 104 104 104 104 105 106 107 111 112 113 114 114 117

Using the Open Database File (OPNDBF) Command . . . . . . . . . . . . . . Using the Open Query File (OPNQRYF) Command Using an Existing Record Format in the File Using a File with a Different Record Format OPNQRYF Examples . . . . . . . . . CL Program Coding with the OPNQRYF Command . . . . . . . . . . . . . The Zero Length Literal and the Contains (*CT) Function . . . . . . . . . . . . . . Selecting Records without Using DDS . . . . Considerations for Creating a File and Using the FORMAT Parameter . . . . . . . . Considerations for Arranging Records . . . . Considerations for DDM Files . . . . . . . Considerations for Writing a High-Level Language Program . . . . . . . . . . Messages Sent When the Open Query File (OPNQRYF) Command Is Run . . . . . . Using the Open Query File (OPNQRYF) Command for More Than Just Input. . . . . Date, Time, and Timestamp Comparisons Using the OPNQRYF Command . . . . . . . . Date, Time, and Timestamp Arithmetic Using OPNQRYF CL Command . . . . . . . . Using the Open Query File (OPNQRYF) Command for Random Processing . . . . . Performance Considerations . . . . . . . Performance Considerations for Sort Sequence Tables . . . . . . . . . . . . . . Performance Comparisons with Other Database Functions . . . . . . . . . . . . . Considerations for Field Use . . . . . . . Considerations for Files Shared in a Job . . . Considerations for Checking If the Record Format Description Changed . . . . . . . Other Run Time Considerations . . . . . . Typical Errors When Using the Open Query File (OPNQRYF) Command . . . . . . . . .

119 121 122 123 125 126 126 127 153 153 153 154 154 155 156 157 161 162 164 168 168 169 170 170 171

Chapter 7. Basic Database File Operations . . . . . . . . . . . . . 173

Setting a Position in the File . . . . . . . Reading Database Records . . . . . . . Reading Database Records Using an Arrival Sequence Access Path . . . . . . . . Reading Database Records Using a Keyed Sequence Access Path . . . . . . . . Waiting for More Records When End of File Is Reached. . . . . . . . . . . . . Releasing Locked Records . . . . . . Updating Database Records . . . . . . . Adding Database Records . . . . . . . . Identifying Which Record Format to Add in a File with Multiple Formats . . . . . . . Using the Force-End-Of-Data Operation . . Deleting Database Records . . . . . . . . 173 . 174 . 174 . 175 . . . . 177 180 180 181

. 182 . 183 . 184

Chapter 6. Opening a Database File

Opening a Database File Member . . . . .

119
. 119

Chapter 8. Closing a Database File . . 187

iv

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 9. Handling Database File Errors in a Program . . . . . . . . . 189

Part 3. Managing Database Files

191

Chapter 10. Managing Database Members . . . . . . . . . . . . . 193

Member Operations Common to All Database Files Adding Members to Files . . . . . . . . Changing Member Attributes . . . . . . . Renaming Members . . . . . . . . . . Removing Members from Files . . . . . . Physical File Member Operations . . . . . . Initializing Data in a Physical File Member . . Clearing Data from Physical File Members . . Reorganizing Data in Physical File Members Displaying Records in a Physical File Member 193 193 193 194 194 194 194 195 195 197

Other Methods to Avoid Rebuilding Access Paths . . . . . . . . . . . . . . . Database Recovery after an Abnormal System End Database File Recovery during the IPL . . . Database File Recovery after the IPL . . . . Database File Recovery Options Table . . . . Storage Pool Paging Option Effect on Database Recovery . . . . . . . . . . . . . .

221 222 222 223 223 224

Chapter 14. Using Source Files . . . . 225

Source File Concepts . . . . . . . . . . Creating a Source File . . . . . . . . . . IBM-Supplied Source Files . . . . . . . . Source File Attributes . . . . . . . . . Creating Source Files without DDS . . . . . Creating Source Files with DDS . . . . . . Working with Source Files . . . . . . . . . Using the Source Entry Utility (SEU) . . . . Using Device Source Files . . . . . . . . Copying Source File Data . . . . . . . . Loading and Unloading Data from Non-AS/400 Systems . . . . . . . . . . . . . . Using Source Files in a Program. . . . . . Creating an Object Using a Source File . . . . Creating an Object from Source Statements in a Batch Job . . . . . . . . . . . . . Determining Which Source File Member Was Used to Create an Object . . . . . . . . Managing a Source File. . . . . . . . . . Changing Source File Attributes . . . . . . Reorganizing Source File Member Data . . . Determining When a Source Statement Was Changed . . . . . . . . . . . . . Using Source Files for Documentation . . . . 225 225 226 226 227 228 228 228 228 228 230 230 231 232 232 233 233 233 234 234

Chapter 11. Changing Database File Descriptions and Attributes . . . . . 199

Effect of Changing Fields in a File Description Changing a Physical File Description and Attributes Example 1 . . . . . . . . . . . . . Example 2 . . . . . . . . . . . . . Changing a Logical File Description and Attributes 199 200 202 202 203

Chapter 12. Using Database Attribute and Cross-Reference Information . . . 205

Displaying Information about Database Files . . . Displaying Attributes for a File . . . . . . Displaying the Descriptions of the Fields in a File . . . . . . . . . . . . . . . Displaying the Relationships between Files on the System . . . . . . . . . . . . . Displaying the Files Used by Programs . . . Displaying the System Cross-Reference Files Writing the Output from a Command Directly to a Database File . . . . . . . . . . . . . Example of Using a Command Output File . . Output File for the Display File Description Command . . . . . . . . . . . . . Output Files for the Display Journal Command Output Files for the Display Problem Command 205 205 206 206 207 208 209 209 210 210 210

Chapter 15. Physical File Constraints

Unique Constraint. . . . . . . . . Primary Key Constraint . . . . . . . Check Constraint . . . . . . . . . Adding Unique, Primary Key, and Check Constraints . . . . . . . . . . . Removing Constraints . . . . . . . Working With Physical File Constraints. . Displaying Check Pending Constraints . . Processing Check Pending Constraints Physical File Constraint Considerations and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

235
. 235 . 235 . 236 . . . . . 236 236 237 238 239

Chapter 13. Database Recovery Considerations . . . . . . . . . . . 213

Database Save and Restore . . . . . . Considerations for Save and Restore . . Database Data Recovery . . . . . . . Journal Management . . . . . . . Transaction Recovery through Commitment Control . . . . . . . . . . . . Force-Writing Data to Auxiliary Storage . Access Path Recovery . . . . . . . . Saving Access Paths . . . . . . . Restoring Access Paths. . . . . . . Journaling Access Paths . . . . . . . . . . . . . . . . . . . . . . . . . . 213 213 214 214 215 216 217 217 217 220

. 240

Chapter 16. Referential Integrity. . . . 241

Introducing Referential Integrity and Referential Constraints . . . . . . . . . . . . . Referential Integrity Terminology . . . . . A Simple Referential Integrity Example . . . Creating a Referential Constraint. . . . . . Constraint Rules . . . . . . . . . . Dening the Parent File . . . . . . . . Dening the Dependent File . . . . . . Verifying Referential Constraints . . . . . Referential Integrity Enforcement. . . . . . Foreign Key Enforcement . . . . . . . . . . . . . . . . . 241 241 242 243 243 245 245 245 246 246

Contents

Parent Key Enforcement . . . . . . . . Constraint States . . . . . . . . . . . . Check Pending . . . . . . . . . . . . Dependent File Restrictions in Check Pending Parent File Restrictions in Check Pending. . . Check Pending and the ADDPFCST Command Examining Check Pending Constraints . . . . Enabling and Disabling a Constraint . . . . . Removing a Constraint . . . . . . . . . . Other AS/400 Functions Affected by Referential Integrity . . . . . . . . . . . . . . . SQL CREATE TABLE . . . . . . . . . SQL ALTER TABLE . . . . . . . . . . Add Physical File Member (ADDPFM) . . . . Change Physical File (CHGPF) . . . . . . Clear Physical File Member (CLRPFM) . . . FORTRAN Force-End-Of-Data (FEOD) . . . Create Duplicate Object (CRTDUPOBJ) . . . Copy File (CPYF) . . . . . . . . . . . Move Object (MOVOBJ) . . . . . . . . Rename Object (RNMOBJ) . . . . . . . Delete File (DLTF) . . . . . . . . . . Remove Physical File Member (RMVM) . . . Save/restore . . . . . . . . . . . . Referential Constraint Considerations and Limitations . . . . . . . . . . . . . . Constraint Cycles . . . . . . . . . . .

246 247 248 249 249 249 249 249 250 251 251 251 251 252 252 252 252 252 253 253 253 253 254 254 254

Appendix A. Database File Sizes . . . 283

Examples . . . . . . . . . . . . . . 287

Appendix B. Double-Byte Character Set (DBCS) Considerations. . . . . . 289

DBCS Field Data Types. . . . . . . . . . DBCS Constants . . . . . . . . . . . DBCS Field Mapping Considerations . . . . . DBCS Field Concatenation . . . . . . . . DBCS Field Substring Operations . . . . . . Comparing DBCS Fields in a Logical File . . . . Using DBCS Fields in the Open Query File (OPNQRYF) Command . . . . . . . . . . Using the Wildcard Function with DBCS Fields Comparing DBCS Fields Through OPNQRYF Using Concatenation with DBCS Fields through OPNQRYF . . . . . . . . . . . . . Using Sort Sequence with DBCS . . . . . 289 289 290 290 291 291 292 292 292 293 294

Appendix C. Database Lock Considerations . . . . . . . . . . . 295 Appendix D. Query Performance: Design Guidelines and Monitoring

. . 299
. . . . . . . . . . . . . . . . . . . . . 299 299 300 301 302 302 325 325 327 327 328 339 341 342 342 343 343 345 345 346 346 347 348

Chapter 17. Triggers. . . . . . . . . 255

Adding a Trigger to a File . . . . . . . . . Removing a Trigger . . . . . . . . . . . Displaying Triggers . . . . . . . . . . . Creating a Trigger Program . . . . . . . . Trigger Program Input Parameters . . . . . Trigger Buffer Section . . . . . . . . . Trigger Program Coding Guidelines and Usages Trigger Program and Commitment Control . . Trigger Program Error Messages . . . . . Sample Trigger Programs . . . . . . . . . Insert Trigger Written in RPG . . . . . . . Update Trigger Written in COBOL . . . . . Delete Trigger Written in ILE C . . . . . . Other AS/400 Functions Impacted by Triggers Save/Restore Base File (SAVOBJ/RSTOBJ) Save/Restore Trigger Program (SAVOBJ/RSTOBJ) . . . . . . . . . . Delete File (DLTF) . . . . . . . . . . Copy File (CPYF) . . . . . . . . . . . Create Duplicate Object (CRTDUPOBJ) . . . Clear Physical File Member (CLRPFM) . . . Initialize Physical File Member (INZPFM) . . . FORTRAN Force-End-Of-Data (FEOD) . . . Apply Journaled Changes or Remove Journaled Changes (APYJRNCHG/RMVJRNCHG) . . . Recommendations for Trigger Programs . . . . Relationship Between Triggers and Referential Integrity . . . . . . . . . . . . . . . 256 257 258 258 258 258 261 262 263 263 264 267 272 277 277 277 277 277 277 277 278 278 278 278 279

Overview . . . . . . . . . . . . . Denition of Terms . . . . . . . . . DB2 for AS/400 Query Component . . . . Data Management Methods . . . . . . . Access Path . . . . . . . . . . . Access Method . . . . . . . . . . The Optimizer . . . . . . . . . . . . Cost Estimation . . . . . . . . . . Access Plan and Validation . . . . . . Optimizer Decision-Making Rules . . . . Join Optimization . . . . . . . . . . Optimizer Messages . . . . . . . . . . Miscellaneous Tips and Techniques . . . . . Avoiding Too Many Indexes . . . . . . ORDER BY and ALWCPYDTA . . . . . Index Usage with the %WLDCRD Function Join Optimization . . . . . . . . . . Avoid Numeric Conversion . . . . . . . Avoid Arithmetic Expressions . . . . . . Controlling Parallel Processing . . . . . . Controlling Parallel Processing System Wide Controlling Parallel Processing for a Job . . Monitoring Database Query Performance . . . Start Database Monitor (STRDBMON) Command . . . . . . . . . . . . End Database Monitor (ENDDBMON) Command . . . . . . . . . . . . Database Monitor Performance Records . . Query Optimizer Index Advisor . . . . . Database Monitor Examples . . . . . . Database Monitor Physical File DDS . . . Database Monitor Logical File DDS . . . .

. 348 . . . . . . 349 350 351 351 358 362

Chapter 18. Database Distribution . . . 281

Appendix E. Using the DB2 for AS/400 Predictive Query Governor . . . . . . 397

vi

OS/400 DB2 for AS/400 Database Programming V4R3

Cancelling a Query . . . . . . . . . . General Implementation Considerations . . . User Application Implementation Considerations Controlling the Default Reply to the Inquiry Message . . . . . . . . . . . . . Using the Governor for Performance Testing . . Examples . . . . . . . . . . . . .

. 398 . 398 398 . 398 . 399 . 399

Trademarks.

. 402

Bibliography . . . . . . . . . . . . 405 Index . . . . . . . . . . . . . . . 407 Readers Comments Wed Like to Hear from You . . . . . . . . . . . 421

Notices . . . . . . . . . . . . . . 401

Contents

vii

viii

OS/400 DB2 for AS/400 Database Programming V4R3

Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. AS/400 Operations Navigator Display DDS for a Physical File (ORDHDRP) DDS for a Simple Logical File (ORDHDRL) DDS for a Field Reference File (DSTREFP) DDS for a Physical File (ORDHDRP) Built from a Field Reference File . . . . . . . DDS for a Logical File (CUSMSTL) . . . . DDS for a Logical File (CUSTMSTL1) Sharing a Record Format . . . . . . . . . . Simple Logical File . . . . . . . . . Simple Logical File with Fields Specied Three Ways to Code Select/Omit Function DDS for a Physical File (ORDDTLP) Built from a Field Reference File . . . . . . . DDS for a Physical File (ORDHDRP) Built from a Field Reference File . . . . . . . DDS for the Logical File ORDFILL . . . . DDS Example for Joining Two Physical Files DDS Example Using the JDUPSEQ Keyword Work with Physical File Constraints Display DSPCPCST Display . . . . . . . . . Edit Check Pending Constraints Display Employee and Department Files . . . . . Referential Integrity State Diagram . . . . Triggers . . . . . . . . . . . . . Triggers Before and After a Change Operation. . . . . . . . . . . . . Methods of Accessing AS/400 Data . . . . xii 8 11 13 15 16 16 39 39 48 54 55 55 63 73 238 239 239 242 248 255 257 301 24. Database Symmetric Multiprocessing 25. Average Number of Duplicate Values of a Three Key Index . . . . . . . . . 26. QSYS/QAQQDBMN Performance Statistics Physical File DDS (1 of 4) . . . . . . 27. QSYS/QAQQDBMN Performance Statistics Physical File DDS (2 of 4) . . . . . . 28. QSYS/QAQQDBMN Performance Statistics Physical File DDS (3 of 4) . . . . . . 29. QSYS/QAQQDBMN Performance Statistics Physical File DDS (4 of 4) . . . . . . 30. Summary record for SQL Information 31. Summary record for Arrival Sequence 32. Summary record for Using Existing Index 33. Summary record for Index Created . . . 34. Summary record for Query Sort . . . . 35. Summary record for Temporary File 36. Summary record for Table Locked . . . 37. Summary record for Access Plan Rebuilt 38. Summary record for Optimizer Timed Out 39. Summary record for Subquery Processing 40. Summary record for Host Variable and ODP Implementation. . . . . . . . . . 41. Summary record for Generic Query Information . . . . . . . . . . . 42. Summary record for STRDBMON/ENDDBMON. . . . . . 43. Detail record for Records Retrieved . . . 304 . 334 . 358 . 359 . 360 . 361 362 367 370 . 373 . 376 378 . 381 383 386 387 . 389 . 391 . 393 . 395

Copyright IBM Corp. 1997, 1998

ix

OS/400 DB2 for AS/400 Database Programming V4R3

About DB2 for AS/400 Database Programming (SC41-5701)

This book contains information about the DB2 for AS/400 database management system, and describes how to set up and use a database on AS/400. This book does not cover in detail all of the capabilities on AS/400 that are related to database. Among the topics not fully described are the relationships of the following topics to database management: v v v v v Structured Query Language (SQL) Data description specications (DDS) Control language (CL) Interactive data denition utility (IDDU) Backup and recovery guidelines and utilities

Who should read this book

This book is intended for the system administrator or programmer who creates and manages les and databases on AS/400. In addition, this book is intended for programmers who use the database in their programs. Before using this book, you should be familiar with the introductory material for using the system. You should also understand how to write a high-level language program for AS/400. Use this book with the high-level language books to get additional database information, tips, and techniques.

AS/400 Operations Navigator

AS/400 Operations Navigator is a powerful graphical interface for Windows 95/NT clients. With AS/400 Operations Navigator, you can use your Windows 95/NT skills to manage and administer your AS/400 systems. v You can work with basic operations (messages, printer output, and printers), job management, system conguration, network administration, security, users and groups, database administration, le systems, and multimedia. v You can schedule regular system backups, work with Interprocess Communication through application development, and manage multiple AS/400 systems through a central system by using Management Central. You can also customize the amount of Operations Navigator function that a user or user group can use through application administration. v You can create a shortcut to any item in the explorer view of Operations Navigator. For example, you can create a shortcut either to Basic Operations or to the items that are listed under Basic Operations (Messages, Printer Output, and Printers). You can even create a shortcut to an individual printer or use a shortcut as a fast way to open the item. Figure 1 on page xii shows an example of the Operations Navigator display:

Copyright IBM Corp. 1997, 1998

xi

Figure 1. AS/400 Operations Navigator Display

IBM recommends that you use this new interface. It has online help to guide you. While we develop this interface, you will still need to use either of the following to do some of your tasks: v Graphical Access (which provides a graphical interface to AS/400 screens). Graphical Access is part of the base Client Access. v A traditional emulator such as PC5250.

Installing Operations Navigator subcomponents

AS/400 Operations Navigator is packaged as separately installable subcomponents. If you are upgrading from a previous release of AS/400 Operations Navigator, only those subcomponents that correspond to the function that is contained in the previous release will be installed. If you are installing for the rst time and you use the Typical or Minimum installation options, the following options are installed by default: v Operations Navigator base support v Basic operations (messages, printer output, and printers) To install additional AS/400 Operations Navigator subcomponents, either use the Custom installation option or use selective setup to add subcomponents after Operations Navigator has been installed: 1. Display the list of currently installed subcomponents in the Component Selection window of Custom installation or selective setup. 2. Select AS/400 Operations Navigator and click Details. 3. Select any additional subcomponents that you want to install and continue with Custom installation or selective setup. Note: To use AS/400 Operations Navigator, you must have Client Access installed on your Windows 95/NT PC and have an AS/400 connection from that PC. For help in connecting your Windows 95/NT PC to your AS/400 system, consult Client Access for Windows 95/NT - Setup, SC41-3512.

Accessing AS/400 Operations Navigator

To access Operations Navigator after you install Client Access and create an AS/400 connection, do the following: 1. Double-click the Client Access folder on your desktop.

xii

OS/400 DB2 for AS/400 Database Programming V4R3

2. Double-click the Operations Navigator icon to open Operations Navigator. You can also drag the icon to your desktop for even quicker access.

Prerequisite and related information

Use the AS/400 Information Center as a starting point for your AS/400 information needs. It is available in either of the following ways: v The Internet at this uniform resource locator (URL) address:
http://publib.boulder.ibm.com/html/as400/infocenter.html

v On CD-ROM: AS/400e series Information Center, SK3T-2027. The AS/400 Information Center contains browsable information on important topics such as Java, program temporary xes (PTFs), and Internet security. It also contains hypertext links to related topics, including Internet links to Web sites such as the AS/400 Technical Studio, the AS/400 Softcopy Library, and the AS/400 home page. For a list of related publications, see the Bibliography on page 405.

How to send your comments

Your feedback is important in helping to provide the most accurate and high-quality information. If you have any comments about this book or any other AS/400 documentation, ll out the readers comment form at the back of this book. v If you prefer to send comments by mail, use the readers comment form with the address that is printed on the back. If you are mailing a readers comment form from a country other than the United States, you can give the form to the local IBM branch office or IBM representative for postage-paid mailing. v If you prefer to send comments by FAX, use either of the following numbers: United States and Canada: 1-800-937-3430 Other countries: 1-507-253-5192 v If you prefer to send comments electronically, use this network ID: IBMMAIL, to IBMMAIL(USIB56RZ) RCHCLERK@us.ibm.com Be sure to include the following: v The name of the book. v The publication number of the book. v The page number or topic to which your comment applies.

About DB2 for AS/400 Database Programming (SC41-5701)

xiii

xiv

OS/400 DB2 for AS/400 Database Programming V4R3

Part 1. Setting Up Database Files

The chapters in this part describe in detail how to set up any AS/400* database le. This includes describing database les and access paths to the system and the different methods that can be used. The ways that your programs use these le descriptions and the differences between using data that is described in a separate le or in the program itself is also discussed. This part includes a chapter with guidelines for describing and creating logical les. This includes information on describing logical le record formats and different types of eld use using data description specications (DDS). Also information is included on describing access paths using DDS as well as using access paths that already exist in the system. Information on dening logical le members to separate the data into logical groups is also included in this chapter. A section on join logical les includes considerations for using join logical les, including examples on how to join physical les and the different ways physical les can be joined. Information on performance, integrity, and a summary of rules for join logical les is also included. There is a chapter on database security in this part which includes information on security functions such as le security, public authority, restricting the ability to change or delete any data in a le, and using logical les to secure data. The different types of authority that can be granted to a user for a database le and the types of authorities you can grant to physical les are also included.

Copyright IBM Corp. 1997, 1998

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 1. General Considerations

This chapter discusses things to consider when you set up any AS/400 database le. Later chapters will discuss unique considerations for setting up physical and logical les.

Describing Database Files

Records in database les can be described in two ways: v Field level description. The elds in the record are described to the system. Some of the things you can describe for each eld include: name, length, data type, validity checks, and text description. Database les that are created with eld level descriptions are referred to as externally described les. v Record level description. Only the length of the record in the le is described to the system. The system does not know about elds in the le. These database les are referred to as program-described les. Regardless of whether a le is described to the eld or record level, you must describe and create the le before you can compile a program that uses that le. That is, the le must exist on the system before you use it. Programs can use le descriptions in two ways: v The program uses the eld-level descriptions that are part of the le. Because the eld descriptions are external to the program itself, the term, externally described data, is used. v The program uses elds that are described in the program itself; therefore, the data is called program-described data. Fields in les that are only described to the record level must be described in the program using the le. Programs can use either externally described or program-described les. However, if you choose to describe a le to the eld level, the system can do more for you. For example, when you compile your programs, the system can extract information from an externally described le and automatically include eld information in your programs. Therefore, you do not have to code the eld information in each program that uses the le. The following gure shows the typical relationships between les and programs on the AS/400 system:

Copyright IBM Corp. 1997, 1998

Externally Described File Field Level Description of a File Externally Described Data (1)

Program Described File Record Level Description of a File Program Described Data (3)

Program Described Data (2)

The program uses the eld level description of a le that is dened to the system. At compilation time, the language compiler copies the external description of the le into the program. The program uses a le that is described to the eld level to the system, but it does not use the actual eld descriptions. At compilation time, the language compiler does not copy the external description of the le into the program. The elds in the le are described in the program. In this case, the eld attributes (for example, eld length) used in the program must be the same as the eld attributes in the external description. The program uses a le that is described only to the record level to the system. The elds in the le must be described in the program.

Externally described les can also be described in a program. You might want to use this method for compatibility with previous systems. For example, you want to run programs on the AS/400 system that originally came from a traditional le system. Those programs use program-described data, and the le itself is only described to the record level. At a later time, you describe the le to the eld level (externally described le) to use more of the database functions available on the system. Your old programs, containing program-described data, can continue to use the externally described le while new programs use the eld-level descriptions that are part of the le. Over time, you can change one or more of your old programs to use the eld level descriptions.

Dictionary-Described Data
A program-described le can be dictionary-described. You can describe the record format information using interactive data denition utility (IDDU). Even though the le is program-described, AS/400 Query, Client Access, and data le utility (DFU) will use the record format description stored in the data dictionary. An externally described le can also be dictionary-described. You can use IDDU to describe a le, then create the le using IDDU. The le created is an externally described le. You can also move into the data dictionary the le description stored in an externally described le. The system always ensures that the denitions in the data dictionary and the description stored in the externally described le are identical.

OS/400 DB2 for AS/400 Database Programming V4R3

Methods of Describing Data to the System

If you want to describe a le just to the record level, you can use the record length (RCDLEN) parameter on the Create Physical File (CRTPF) and Create Source Physical File (CRTSRCPF) commands. If you want to describe your le to the eld level, several methods can be used to describe data to the database system: IDDU, SQL* commands, or data description specications (DDS). Note: Because DDS has the most options for dening data for the programmer, this guide will focus on describing database les using DDS.

OS/400 Interactive Data Denition Utility (IDDU)

Physical les can be described using IDDU. You might use IDDU because it is a menu-driven, interactive method of describing data. You also might be familiar with describing data using IDDU on a System/36. In addition, IDDU allows you to describe multiple-format physical les for use with Query, Client Access, and DFU. When you use IDDU to describe your les, the le denition For more information about IDDU, see IDDU Use book.

DB2 for AS/400 Structured Query Language (SQL)

The Structured Query Language can be used to describe an AS/400 database le. The SQL language supports statements to describe the elds in the database le, and to create the le. SQL was created by IBM to meet the need for a standard and common database language. It is currently used on all IBM DB2 platforms and on many other database implementations from many different manufacturers. When database les are created using the DB2 for AS/400 SQL language, the description of the le is automatically added to a data dictionary in the SQL collection. The data dictionary (or catalog) is then automatically maintained by the system. The SQL language is the language of choice for accessing databases on many other platforms. It is the only language for distributed database and heterogeneous systems. For more information about SQL, see the DB2 for AS/400 SQL Programming and DB2 for AS/400 SQL Reference books.

OS/400 Data Description Specications (DDS)

Externally described data les can be described using DDS. Using DDS, you provide descriptions of the eld, record, and le level information. You might use DDS because it provides the most options for the programmer to describe data in the database. For example, only with DDS can you describe key elds in logical les.

Chapter 1. General Considerations

The DDS Form provides a common format for describing data externally. DDS data is column sensitive. The examples in this manual have numbered columns and show the data in the correct columns. The DDS Reference book contains a detailed description of DDS functions to describe physical and logical les.

Describing a Database File to the System

When you describe a database le to the system, you describe the two major parts of that le: the record format and the access path.

Describing the Record Format

The record format describes the order of the elds in each record. The record format also describes each eld in detail including: length, data type (for example, packed decimal or character), validity checks, text description, and other information. The following example shows the relationship between the record format and the records in a physical le:
Specifications for Record Format ITMMST: Field Description ITEM Zoned decimal, 5 digits, 0 decimal positions DESCRP Character, 18 positions PRICE Zoned decimal, 5 digits, 2 decimal positions Records: ITEM DESCRP PRICE 35406HAMMER 01486 92201SCREWDRIVER 00649

A physical le can have only one record format. The record format in a physical le describes the way the data is actually stored. A logical le contains no data. Logical les are used to arrange data from one or more physical les into different formats and sequences. For example, a logical le could change the order of the elds in the physical le, or present to the program only some of the elds stored in the physical le. A logical le record format can change the length and data type of elds stored in physical les. The system does the necessary conversion between the physical le eld description and the logical le eld description. For example, a physical le could describe FLDA as a packed decimal eld of 5 digits and a logical le using FLDA might redene it as a zoned decimal eld of 7 digits. In this case, when your program used the logical le to read a record, the system would automatically convert (unpack) FLDA to zoned decimal format.

OS/400 DB2 for AS/400 Database Programming V4R3

Describing the Access Path

An access path describes the order in which records are to be retrieved. When you describe an access path, you describe whether it will be a keyed sequence or arrival sequence access path. Access paths are discussed in more detail in Describing the Access Path for the File on page 17.

Naming Conventions
The le name, record format name, and eld name can be as long as 10 characters and must follow all system naming conventions, but you should keep in mind that some high-level languages have more restrictive naming conventions than the system does. For example, the RPG/400* language allows only 6-character names, while the system allows 10-character names. In some cases, you can temporarily change (rename) the system name to one that meets the high-level language restrictions. For more information about renaming database elds in programs, see your high-level language guide. In addition, names must be unique as follows: v Field names must be unique in a record format. v Record format names and member names must be unique in a le. v File names must be unique in a library.

Describing Database Files Using DDS

When you describe a database le using DDS, you can describe information at the le, record format, join, eld, key, and select/omit levels: v File level DDS give the system information about the entire le. For example, you can specify whether all the key eld values in the le must be unique. v Record format level DDS give the system information about a specic record format in the le. For example, when you describe a logical le record format, you can specify the physical le that it is based on. v Join level DDS give the system information about physical les used in a join logical le. For example, you can specify how to join two physical les. v Field level DDS give the system information about individual elds in the record format. For example, you can specify the name and attributes of each eld. v Key eld level DDS give the system information about the key elds for the le. For example, you can specify which elds in the record format are to be used as key elds. v Select/omit eld level DDS give the system information about which records are to be returned to the program when processing the le. Select/omit specications apply to logical les only.

Example of Describing a Physical File Using DDS

The DDS for a physical le must be in the following order ( Figure 2 on page 8): 1 File level entries (optional). The UNIQUE keyword is used to indicate that the value of the key eld in each record in the le must be unique. Duplicate key values are not allowed in this le. Record format level entries. The record format name is specied, along with an optional text description.

Chapter 1. General Considerations

3 4 5

Field level entries. The eld names and eld lengths are specied, along with an optional text description for each eld. Key eld level entries (optional). The eld names used as key elds are specied. Comment (optional).

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER HEADER FILE (ORDHDRP) A 5 A 1 UNIQUE A 2 R ORDHDR TEXT('Order header record') A 3 CUST 5 0 TEXT('Customer number') A ORDER 5 0 TEXT('Order number') A . A . A . A K CUST A 4 K ORDER

Figure 2. DDS for a Physical File (ORDHDRP)

The following example shows a physical le ORDHDRP (an order header le), which has an arrival sequence access path without key elds specied, and the DDS necessary to describe that le.
Record Format (ORDHDR) / Purchase / Customer Order Order Order Shipping Order / Number Number Date Number Instructions Status / (CUST) (ORDER) (ORDATE) (CUSORD) (SHPVIA) (ORDSTS) /. . / Packed Packed Packed Packed Character Character Decimal Decimal Decimal Decimal Length 15 Length 1 Length 5 Length 5 Length 6 Length 15 0 Dec Pos 0 Dec Pos 0 Dec Pos 0 Dec Pos / / / / State ./ (STATE) / Character Length 2

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER HEADER FILE (ORDHDRP) A R ORDHDR TEXT('Order header record') A CUST 5 0 TEXT('Customer Number') A ORDER 5 0 TEXT('Order Number') A ORDATE 6 0 TEXT('Order Date') A CUSORD 15 0 TEXT('Customer Order No.') A SHPVIA 15 TEXT('Shipping Instr') A ORDSTS 1 TEXT('Order Status') A OPRNME 10 TEXT('Operator Name') A ORDAMT 9 2 TEXT('Order Amount') A CUTYPE 1 TEXT('Customer Type') A INVNBR 5 0 TEXT('Invoice Number') A PRTDAT 6 0 TEXT('Printed Date') A SEQNBR 5 0 TEXT('Sequence Number') A OPNSTS 1 TEXT('Open Status') A LINES 3 0 TEXT('Order Lines') A ACTMTH 2 0 TEXT('Accounting Month') A ACTYR 2 0 TEXT('Accounting Year') A STATE 2 TEXT('State') A

OS/400 DB2 for AS/400 Database Programming V4R3

The R in position 17 indicates that a record format is being dened. The record format name ORDHDR is specied in positions 19 through 28. You make no entry in position 17 when you are describing a eld; a blank in position 17 along with a name in positions 19 through 28 indicates a eld name. The data type is specied in position 35. The valid data types are: Entry A P S B F H L T Z Notes: 1. For double-byte character set (DBCS) data types, see Appendix B. Double-Byte Character Set (DBCS) Considerations. 2. The AS/400 system performs arithmetic operations more efficiently for packed decimal than for zoned decimal. 3. Some high-level languages do not support oating-point data. 4. Some special considerations that apply when you are using oating-point elds are: v The precision associated with a oating-point eld is a function of the number of bits (single or double precision) and the internal representation of the oating-point value. This translates into the number of decimal digits supported in the signicant and the maximum values that can be represented in the oating-point eld. v When a oating-point eld is dened with fewer digits than supported by the precision specied, that length is only a presentation length and has no effect on the precision used for internal calculations. v Although oating-point numbers are accurate to 7 (single) or 15 (double) decimal digits of precision, you can specify up to 9 or 17 digits. You can use the extra digits to uniquely establish the internal bit pattern in the internal oating-point format so identical results are obtained when a oating-point number in internal format is converted to decimal and back again to internal format. If the data type (position 35) is not specied, the decimal positions entry is used to determine the data type. If the decimal positions (positions 36 through 37) are blank, the data type is assumed to be character (A); if these positions contain a number 0 through 31, the data type is assumed to be packed decimal (P). The length of the eld is specied in positions 30 through 34, and the number of decimal positions (for numeric elds) is specied in positions 36 and 37. If a packed or zoned decimal eld is to be used in a high-level language program, the eld length must be limited to the length allowed by the high-level language you
Chapter 1. General Considerations

Meaning Character Packed decimal Zoned decimal Binary Floating point Hexadecimal Date Time Timestamp

are using. The length is not the length of the eld in storage but the number of digits or characters specied externally from storage. For example, a 5-digit packed decimal eld has a length of 5 specied in DDS, but it uses only 3 bytes of storage. Character or hexadecimal data can be dened as variable length by specifying the VARLEN eld level keyword. Generally you would use variable length elds, for example, as an employee name within a database. Names usually can be stored in a 30-byte eld; however, there are times when you need 100 bytes to store a very long name. If you always dene the eld as 100 bytes, you waste storage. If you always dene the eld as 30 bytes, some names are truncated. You can use the DDS VARLEN keyword to dene a character eld as variable length. You can dene this eld as: v Variable-length with no allocated length. This allows the eld to be stored using only the number of bytes equal to the data (plus two bytes per eld for the length value and a few overhead bytes per record). However, performance might be affected because all data is stored in the variable portion of the le, which requires two disk read operations to retrieve. v Variable-length with an allocated length equal to the most likely size of the data. This allows most eld data to be stored in the xed portion of the le and minimizes unused storage allocations common with xed-length eld denitions. Only one read operation is required to retrieve eld data with a length less than the allocated eld length. Field data with a length greater than the allocated length is stored in the variable portion of the le and requires two read operations to retrieve the data.

Example of Describing a Logical File Using DDS

The DDS for a logical le must be in the following order ( Figure 3 on page 11): 1 File level entries (optional). In this example, the UNIQUE keyword indicates that for this le the key value for each record must be unique; no duplicate key values are allowed.

For each record format: 2 3 4 5 Record format level entries. In this example, the record format name, the associated physical le, and an optional text description are specied. Field level entries (optional). In this example, each eld name used in the record format is specied. Key eld level entries (optional). In this example, the Order eld is used as a key eld. Select/omit eld level entries (optional). In this example, all records whose Opnsts eld contains a value of N are omitted from the les access path. That is, programs reading records from this le will never see a record whose Opnsts eld contains an N value. Comment.

10

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER HEADER FILE (ORDHDRP) A 6 A 1 UNIQUE A 2 R ORDHDR PFILE(ORDHDRP) A 3 ORDER TEXT('Order number') A CUST TEXT('Customer number') A . A . A . A 4 K ORDER A O OPNSTS 5 CMP(EQ 'N') A S ALL

Figure 3. DDS for a Simple Logical File (ORDHDRL)

A logical le must be created after all physical les on which it is based are created. The PFILE keyword in the previous example is used to specify the physical le or les on which the logical le is based. Record formats in a logical le can be: v A new record format based on elds from a physical le v The same record format as in a previously described physical or logical le (see Sharing Existing Record Format Descriptions on page 15) Fields in the logical le record format must either appear in the record format of at least one of the physical les or be derived from the elds of the physical les on which the logical le is based. For more information about describing logical les, see Chapter 3. Setting Up Logical Files.

Additional Field Denition Functions

You can describe additional information about the elds in the physical and logical le record formats with function keywords (positions 45 through 80 on the DDS Form). Some of the things you can specify include: v Validity checking keywords to verify that the eld data meets your standards. For example, you can describe a eld to have a valid range of 500 to 900. (This checking is done only when data is typed on a keyboard to the display.) v Editing keywords to control how a eld should be displayed or printed. For example, you can use the EDTCDE(Y) keyword to specify that a date eld is to appear as MM/DD/YY. The EDTCDE and EDTWRD keywords can be used to control editing. (This editing is done only when used in a display or printer le.) v Documentation, heading, and name control keywords to control the description and name of a eld. For example, you can use the TEXT keyword to document a description of each eld. This text description is included in your compiler list to better document the les used in your program. The TEXT and COLHDG keywords control text and column-heading denitions. The ALIAS keyword can be used to provide a more descriptive name for a eld. The alias, or alternative name, is used in a program (if the high-level language supports alias names). v Content and default value keywords to control the null content and default data for a eld. The ALWNULL keyword species whether a null value is allowed in the eld. If ALWNULL is used, the default value of the eld is null. If ALWNULL is not present at the eld level, the null value is not allowed,

Chapter 1. General Considerations

11

character and hexadecimal elds default to blanks, and numeric elds default to zeros, unless the DFT (default) keyword is used to specify a different value.

Using Existing Field Descriptions and Field Reference Files

If a eld was already described in an existing le, and you want to use that eld description in a new le you are setting up, you can request the system to copy that description into your new le description. The DDS keywords REF and REFFLD allow you to refer to a eld description in an existing le. This helps reduce the effort of coding DDS statements. It also helps ensure that the eld attributes are used consistently in all les that use the eld. In addition, you can create a physical le for the sole purpose of using its eld descriptions. That is, the le does not contain data; it is used only as a reference for the eld descriptions for other les. This type of le is known as a eld reference le. A eld reference le is a physical le containing no data, just eld descriptions. You can use a eld reference le to simplify record format descriptions and to ensure eld descriptions are used consistently. You can dene all the elds you need for an application or any group of les in a eld reference le. You can create a eld reference le using DDS and the Create Physical File (CRTPF) command. After the eld reference le is created, you can build physical le record formats from this le without describing the characteristics of each eld in each le. When you build physical les, all you need to do is refer to the eld reference le (using the REF and REFFLD keywords) and specify any changes. Any changes to the eld descriptions and keywords specied in your new le override the descriptions in the eld reference le. In the following example, a eld reference le named DSTREFP is created for distribution applications. Figure 4 on page 13 shows the DDS needed to describe DSTREFP.

12

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* FIELD REFERENCE FILE (DSTREFP) A R DSTREF TEXT('Field reference file') A A* FIELDS DEFINED BY CUSTOMER MASTER RECORD (CUSMST) A CUST 5 0 TEXT('Customer numbers') A COLHDG('CUSTOMER' 'NUMBER') A NAME 20 TEXT('Customer name') A ADDR 20 TEXT('Customer address') A A CITY 20 TEXT('Customer city') A A STATE 2 TEXT('State abbreviation') A CHECK(MF) A CRECHK 1 TEXT('Credit check') A VALUES('Y' 'N') A SEARCH 6 0 TEXT('Customer name search') A COLHDG('SEARCH CODE') A ZIP 5 0 TEXT('Zip code') A CHECK(MF) A CUTYPE 15 COLHDG('CUSTOMER' 'TYPE') A RANGE(1 5) A A* FIELDS DEFINED BY ITEM MASTER RECORD (ITMAST) A ITEM 5 TEXT('Item number') A COLHDG('ITEM' 'NUMBER') A CHECK(M10) A DESCRP 18 TEXT('Item description') A PRICE 5 2 TEXT('Price per unit') A EDTCDE(J) A CMP(GT 0) A COLHDG('PRICE') A ONHAND 5 0 TEXT('On hand quantity') A EDTCDE(Z) A CMP(GE 0) A COLHDG('ON HAND') A WHSLOC 3 TEXT('Warehouse location') A CHECK(MF) A COLHDG('BIN NO') A ALLOC R REFFLD(ONHAND *SRC) A TEXT('Allocated quantity') A CMP(GE 0) A COLHDG('ALLOCATED') A A* FIELDS DEFINED BY ORDER HEADER RECORD (ORDHDR) A ORDER 5 0 TEXT('Order number') A COLHDG('ORDER' 'NUMBER') A ORDATE 6 0 TEXT('Order date') A EDTCDE(Y) A COLHDG('DATE' 'ORDERED') A CUSORD 15 TEXT('Cust purchase ord no.') A COLHDG('P.O.' 'NUMBER') A SHPVIA 15 TEXT('Shipping instructions') A ORDSTS 1 TEXT('Order status code') A COLHDG('ORDER' 'STATUS') A OPRNME R REFFLD(NAME *SRC) A TEXT('Operator name') A COLHDG('OPERATOR NAME') A ORDAMT 9 2 TEXT('Total order value') A COLHDG('ORDER' 'AMOUNT') A

Figure 4. DDS for a Field Reference File (DSTREFP) (Part 1 of 2)

Chapter 1. General Considerations

13

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A INVNBR 5 0 TEXT('Invoice number') A COLHDG('INVOICE' 'NUMBER') A PRTDAT 6 0 EDTCDE(Y) A COLHDG('PRINTED' 'DATE') A SEQNBR 5 0 TEXT('Sequence number') A COLHDG('SEQ' 'NUMBER') A OPNSTS 1 TEXT('Open status') A COLHDG('OPEN' 'STATUS') A LINES 3 0 TEXT('Lines on invoice') A COLHDG('TOTAL' 'LINES') A ACTMTH 2 0 TEXT('Accounting month') A COLHDG('ACCT' 'MONTH') A ACTYR 2 0 TEXT('Accounting year') A COLHDG('ACCT' 'YEAR') A A* FIELDS DEFINED BY ORDER DETAIL/LINE ITEM RECORD (ORDDTL) A LINE 3 0 TEXT('Line no. this item') A COLHDG('LINE' 'NO') A QTYORD 3 0 TEXT('Quantity ordered') A COLHDG('QTY' 'ORDERED' A CMP(GE 0) A EXTENS 6 2 TEXT('Ext of QTYORD x PRICE') A EDTCDE(J) A COLHDG('EXTENSION') A A* FIELDS DEFINED BY ACCOUNTS RECEIVABLE A ARBAL 8 2 TEXT('A/R balance due') A EDTCDE(J) A A* WORK AREAS AND OTHER FIELDS THAT OCCUR IN MULTIPLE PROGRAMS A STATUS 12 TEXT('status description') A

Figure 4. DDS for a Field Reference File (DSTREFP) (Part 2 of 2)

Assume that the DDS in Figure 4 is entered into a source le FRSOURCE; the member name is DSTREFP. To then create a eld reference le, use the Create Physical File (CRTPF) command as follows:
CRTPF FILE(DSTPRODLB/DSTREFP) SRCFILE(QGPL/FRSOURCE) MBR(*NONE) TEXT('Distribution field reference file')

The parameter MBR(*NONE) tells the system not to add a member to the le (because the eld reference le never contains data and therefore does not need a member). To describe the physical le ORDHDRP by referring to DSTREFP, use the following DDS ( Figure 5 on page 15):

14

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER HEADER FILE (ORDHDRP) - PHYSICAL FILE RECORD DEFINITION A REF(DSTREFP) A R ORDHDR TEXT('Order header record') A CUST R A ORDER R A ORDATE R A CUSORD R A SHPVIA R A ORDSTS R A OPRNME R A ORDAMT R A CUTYPE R A INVNBR R A PRTDAT R A SEQNBR R A OPNSTS R A LINES R A ACTMTH R A ACTYR R A STATE R A

Figure 5. DDS for a Physical File (ORDHDRP) Built from a Field Reference File

The REF keyword (positions 45 through 80) with DSTREFP (the eld reference le name) specied indicates the le from which eld descriptions are to be used. The R in position 29 of each eld indicates that the eld description is to be taken from the reference le. When you create the ORDHDRP le, the system uses the DSTREFP le to determine the attributes of the elds included in the ORDHDR record format. To create the ORDHDRP le, use the Create Physical File (CRTPF) command. Assume that the DDS in Figure 5 was entered into a source le QDDSSRC; the member name is ORDHDRP.
CRTPF FILE(DSTPRODLB/ORDHDRP) TEXT('Order Header physical file')

Note: The les used in some of the examples in this guide refer to this eld reference le.

Using a Data Dictionary for Field Reference

You can use a data dictionary and IDDU as an alternative to using a DDS eld reference le. IDDU allows you to dene elds in a data dictionary. For more information, see the IDDU Use book.

Sharing Existing Record Format Descriptions

A record format can be described once in either a physical or a logical le (except a join logical le) and can be used by many les. When you describe a new le, you can specify that the record format of an existing le is to be used by the new le. This can help reduce the number of DDS statements that you would normally code to describe a record format in a new le and can save auxiliary storage space. The le originally describing the record format can be deleted without affecting the les sharing the record format. After the last le using the record format is deleted, the system automatically deletes the record format description.

Chapter 1. General Considerations

15

The following shows the DDS for two les. The rst le describes a record format, and the second shares the record format of the rst:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RECORD1 PFILE(CUSMSTP) A CUST A NAME A ADDR A SEARCH A K CUST A

Figure 6. DDS for a Logical File (CUSMSTL)

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RECORD1 PFILE(CUSMSTP) A FORMAT(CUSMSTL) A K NAME A

Figure 7. DDS for a Logical File (CUSTMSTL1) Sharing a Record Format

The example shown in Figure 6 shows le CUSMSTL, in which the elds Cust, Name, Addr, and Search make up the record format. The Cust eld is specied as a key eld. The DDS in Figure 7 shows le CUSTMSTL1, in which the FORMAT keyword names CUSMSTL to supply the record format. The record format name must be RECORD1, the same as the record format name shown in Figure 6. Because the les are sharing the same format, both les have elds Cust, Name, Addr, and Search in the record format. In le CUSMSTL1, a different key eld, Name is specied. The following restrictions apply to shared record formats: v A physical le cannot share the format of a logical le. v A join logical le cannot share the format of another le, and another le cannot share the format of a join logical le. v A view cannot share the format of another le, and another le cannot share the format of a view. (In SQL, a view is an alternative representation of data from one or more tables. A view can include all or some of the columns contained in the table or tables on which it is dened.) If the original record format is changed by deleting all related les and creating the original le and all the related les again, it is changed for all les that share it. If only the le with the original format is deleted and re-created with a new record format, all les previously sharing that les format continue to use the original format. If a logical le is dened but no eld descriptions are specied and the FORMAT keyword is not specied, the record format of the rst physical le (specied rst on the PFILE keyword for the logical le) is automatically shared. The record format name specied in the logical le must be the same as the record format name specied in the physical le. To nd out if a le shares a format with another le, use the RCDFMT parameter on the Display Database Relations (DSPDBR) command.

16

OS/400 DB2 for AS/400 Database Programming V4R3

| | | | | | | | | |

Record Format Relationships: When you change, add, and delete elds with the Change Physical File (CHGPF) command, the following relationships exist between the physical and logical les that share the same record format: v When you change the length of a eld in a physical le, you will also change the length of the logical les eld. v When you add a eld to the physical le, the eld is also added to the logical le. v When you delete a eld in the physical le, the eld will be deleted from the logical le unless there is another dependency in the DDS, such as a keyed eld or a select or omit statement. Record Format Sharing Limitation: A record format can only be shared by 32K objects. Error messages are issued when you reach the limitation. You may encounter this limitation in a circumstance where you are duplicating the same database object multiple times. Note: Format sharing is performed for les that are duplicated. The format is shared up to 32,767 times. Beyond that, if a le that shares the format is duplicated, a new format will be created for the duplicated le.

Describing the Access Path for the File

An access path describes the order in which records are to be retrieved. Records in a physical or logical le can be retrieved using an arrival sequence access path or a keyed sequence access path. For logical les, you can also select and omit records based on the value of one or more elds in each record.

Arrival Sequence Access Path

The arrival sequence access path is based on the order in which the records arrive and are stored in the le. For reading or updating, records can be accessed: v Sequentially, where each record is taken from the next sequential physical position in the le. v Directly by relative record number, where the record is identied by its position from the start of the le. An externally described le has an arrival sequence access path when no key elds are specied for the le. An arrival sequence access path is valid only for the following: v Physical les v Logical les in which each member of the logical le is based on only one physical le member v Join logical les v Views Notes: 1. Arrival sequence is the only processing method that allows a program to use the storage space previously occupied by a deleted record by placing another record in that storage space. This method requires explicit insertion of a record given a relative record number that you provide. Another method, in which the system manages the space created by deleting records, is the reuse deleted records attribute that can be specied for physical les. For more information
Chapter 1. General Considerations

17

and tips on using the reuse deleted records attribute, see Reusing Deleted Records on page 99. For more information about processing deleted records, see Deleting Database Records on page 184. 2. Through your high-level language, the Display Physical File Member (DSPPFM) command, and the Copy File (CPYF) command, you can process a keyed sequence le in arrival sequence. You can use this function for a physical le, a simple logical le based on one physical le member, or a join logical le. 3. Through your high-level language, you can process a keyed sequence le directly by relative record number. You can use this function for a physical le, a simple logical le based on one physical le member, or a join logical le. 4. An arrival sequence access path does not take up any additional storage and is always saved or restored with the le. (Because the arrival sequence access path is nothing more than the physical order of the data as it was stored, when you save the data you save the arrival sequence access path.)

Keyed Sequence Access Path

A keyed sequence access path is based on the contents of the key elds as dened in DDS. This type of access path is updated whenever records are added or deleted, or when records are updated and the contents of a key eld is changed. The keyed sequence access path is valid for both physical and logical les. The sequence of the records in the le is dened in DDS when the le is created and is maintained automatically by the system. Key elds dened as character elds are arranged based on the sequence dened for EBCDIC characters. Key elds dened as numeric elds are arranged based on their algebraic values, unless the UNSIGNED (unsigned value) or ABSVAL (absolute value) DDS keywords are specied for the eld. Key elds dened as DBCS are allowed, but are arranged only as single bytes based on their bit representation. Arranging Key Fields Using an Alternative Collating Sequence: Keyed elds that are dened as character elds can be arranged based either on the sequence for EBCDIC characters or on an alternative collating sequence. Consider the following records:
Record 1 2 3 4 5 Empname Jones, Mary Smith, Ron JOHNSON, JOHN Smith, ROBERT JONES, MARTIN Deptnbr 45 45 53 27 53 Empnbr 23318 41321 41322 56218 62213

If the Empname is the key eld and is a character eld, using the sequence for EBCDIC characters, the records would be arranged as follows:
Record 1 3 5 2 4 Empname Jones, Mary JOHNSON, JOHN JONES, MARTIN Smith, Ron Smith, ROBERT Deptnbr 45 53 53 45 27 Empnbr 23318 41322 62213 41321 56218

18

OS/400 DB2 for AS/400 Database Programming V4R3

Notice that the EBCDIC sequence causes an unexpected sort order because the lowercase characters are sorted before uppercase characters. Thus, Smith, Ron sorts before Smith, ROBERT. An alternative collating sequence could be used to sort the records when the records were entered using uppercase and lowercase as shown in the following example:
Record 3 5 1 4 2 Empname JOHNSON, JOHN JONES, MARTIN Jones, Mary Smith, ROBERT Smith, Ron Deptnbr 53 53 45 27 45 Empnbr 41322 62213 23318 56218 41321

To use an alternative collating sequence for a character key eld, specify the ALTSEQ DDS keyword, and specify the name of the table containing the alternative collating sequence. When setting up a table, each 2-byte position in the table corresponds to a character. To change the order in which a character is sorted, change its 2-digit value to the same value as the character it should be sorted equal to. For more information about the ALTSEQ keyword, see the DDS Reference book. For information about sorting uppercase and lowercase characters regardless of their case, the QCASE256 table in library QUSRSYS is provided for you. Arranging Key Fields Using the SRTSEQ Parameter: You can arrange key elds containing character data according to several sorting sequences available with the SRTSEQ parameter. Consider the following records:
Record 1 2 3 4 5 6 Empname Jones, Marilyn Smith, Ron JOHNSON, JOHN Smith, ROBERT JONES, MARTIN Jones, Martin Deptnbr 45 45 53 27 53 08 Empnbr 23318 41321 41322 56218 62213 29231

If the Empname eld is the key eld and is a character eld, the *HEX sequence (the EBCDIC sequence) arranges the records as follows:
Record 1 6 3 5 2 4 Empname Jones, Marilyn Jones, Martin JOHNSON, JOHN JONES, MARTIN Smith, Ron Smith, ROBERT Deptnbr 45 08 53 53 45 27 Empnbr 23318 29231 41322 62213 41321 56218

Notice that with the *HEX sequence, all lowercase characters are sorted before the uppercase characters. Thus, Smith, Ron sorts before Smith, ROBERT, and JOHNSON, JOHN sorts between the lowercase and uppercase Jones. You can use the *LANGIDSHR sort sequence to sort records when the records were entered using a mixture of uppercase and lowercase. The *LANGIDSHR sequence, which uses the same collating weight for lowercase and uppercase characters, results in the following:

Chapter 1. General Considerations

19

Record 3 1 5 6 4 2

Empname JOHNSON, JOHN Jones, Marilyn JONES, MARTIN Jones, Martin Smith, ROBERT Smith, Ron

Deptnbr 53 45 53 08 27 45

Empnbr 41322 23318 62213 29231 56218 41321

Notice that with the *LANGIDSHR sequence, the lowercase and uppercase characters are treated as equal. Thus, JONES, MARTIN and Jones, Martin are equal and sort in the same sequence they have in the base le. While this is not incorrect, it would look better in a report if all the lowercase Jones preceded the uppercase JONES. You can use the *LANGIDUNQ sort sequence to sort the records when the records were entered using an inconsistent uppercase and lowercase. The *LANGIDUNQ sequence, which uses different but sequential collating weights for lowercase and uppercase characters, results in the following:
Record 3 1 6 5 4 2 Empname JOHNSON, JOHN Jones, Marilyn Jones, Martin JONES, MARTIN Smith, ROBERT Smith, Ron Deptnbr 53 45 08 53 27 45 Empnbr 41322 23318 29231 62213 56218 41321

The *LANGIDSHR and *LANGIDUNQ sort sequences exist for every language supported in your system. The LANGID parameter determines which *LANGIDSHR or *LANGIDUNQ sort sequence to use. Use the SRTSEQ parameter to specify the sort sequence and the LANGID parameter to specify the language. Arranging Key Fields in Ascending or Descending Sequence: Key elds can be arranged in either ascending or descending sequence. Consider the following records:
Record 1 2 3 4 5 6 Empnbr 56218 41322 64002 23318 41321 62213 Clsnbr 412 412 412 412 412 412 Clsnam Welding Welding Welding Welding Welding Welding Cpdate 032188 011388 011388 032188 051888 032188

I I I I I I

If the Empnbr eld is the key eld, the two possibilities for organizing these records are: v In ascending sequence, where the order of the records in the access path is:
Record 4 5 2 1 6 3 Empnbr 23318 41321 41322 56218 62213 64002 Clsnbr 412 412 412 412 412 412 Clsnam Welding Welding Welding Welding Welding Welding Cpdate 032188 051888 011388 032188 032188 011388

I I I I I I

20

OS/400 DB2 for AS/400 Database Programming V4R3

v In descending sequence, where the order of the records in the access path is:
Record 3 6 1 2 5 4 Empnbr 64002 62213 56218 41322 41321 23318 Clsnbr 412 412 412 412 412 412 Clsnam Welding Welding Welding Welding Welding Welding Cpdate 011388 032188 032188 011388 051888 032188

I I I I I I

When you describe a key eld, the default is ascending sequence. However, you can use the DESCEND DDS keyword to specify that you want to arrange a key eld in descending sequence. Using More Than One Key Field: You can use more than one key eld to arrange the records in a le. The key elds do not have to use the same sequence. For example, when you use two key elds, one eld can use ascending sequence while the other can use descending sequence. Consider the following records:
Record 1 2 3 4 5 Order 52218 41834 41834 52218 41834 Ordate 063088 062888 062888 063088 062888 Line 01 03 02 02 01 Item 88682 42111 61132 40001 00623 Qtyord 425 30 4 62 50 Extens 031875 020550 021700 021700 025000

If the access path uses the Order eld, then the Line eld as the key elds, both in ascending sequence, the order of the records in the access path is:
Record 5 3 2 1 4 Order 41834 41834 41834 52218 52218 Ordate 062888 062888 062888 063088 063088 Line 01 02 03 01 02 Item 00623 61132 42111 88682 40001 Qtyord 50 4 30 425 62 Extens 025000 021700 020550 031875 021700

If the access path uses the key eld Order in ascending sequence, then the Line eld in descending sequence, the order of the records in the access path is:
Record 2 3 5 4 1 Order 41834 41834 41834 52218 52218 Ordate 062888 062888 062888 063088 063088 Line 03 02 01 02 01 Item 42111 61132 00623 40001 88682 Qtyord 30 4 50 62 425 Extens 020550 021700 025000 021700 031875

When a record has key elds whose contents are the same as the key eld in another record in the same le, then the le is said to have records with duplicate key values. However, the duplication must occur for all key elds for a record if they are to be called duplicate key values. For example, if a record format has two key elds Order and Ordate, duplicate key values occur when the contents of both the Order and Ordate elds are the same in two or more records. These records have duplicate key values:

Chapter 1. General Considerations

21

Order 41834 41834 41834

Ordate 062888 062888 062888

Line 03 02 01

Item 42111 61132 00623

Qtyord 30 04 50

Extens 020550 021700 025000

Using the Line eld as a third key eld denes the le so that there are no duplicate keys:
(First Key Field) (Second Key Order Field) Ordate 41834 062888 41834 062888 41834 062888 (Third Key Field) Line 03 02 01 Item 42111 61132 00623 Qtyord 30 04 50 Extens 020550 021700 025000

A logical le that has more than one record format can have records with duplicate key values, even though the record formats are based on different physical les. That is, even though the key values come from different record formats, they are considered duplicate key values. Preventing Duplicate Key Values: The AS/400 database management system allows records with duplicate key values in your les. However, you may want to prevent duplicate key values in some of your les. For example, you can create a le where the key eld is dened as the customer number eld. In this case, you want the system to ensure that each record in the le has a unique customer number. You can prevent duplicate key values in your les by specifying the UNIQUE keyword in DDS. With the UNIQUE keyword specied, a record cannot be entered or copied into a le if its key value is the same as the key value of a record already existing in the le. You can also use unique constraints to enforce the integrity of unique keys. For details on the supported constraints, see Chapter 15. Physical File Constraints. If records with duplicate key values already exist in a physical le, the associated logical le cannot have the UNIQUE keyword specied. If you try to create a logical le with the UNIQUE keyword specied, and the associated physical le contains duplicate key values, the logical le is not created. The system sends you a message stating this and sends you messages (as many as 20) indicating which records contain duplicate key values. When the UNIQUE keyword is specied for a le, any record added to the le cannot have a key value that duplicates the key value of an existing record in the le, regardless of the le used to add the new record. For example, two logical les LF1 and LF2 are based on the physical le PF1. The UNIQUE keyword is specied for LF1. If you use LF2 to add a record to PF1, you cannot add the record if it causes a duplicate key value in LF1. If any of the key elds allow null values, null values that are inserted into those elds may or may not cause duplicates depending on how the access path was dened at the time the le was created. The *INCNULL parameter of the UNIQUE keyword indicates that null values are included when determining whether duplicates exist in the unique access path. The *EXCNULL parameter indicates that null values are not included when determining whether duplicate values exist. For more information, see the DDS Reference book.

22

OS/400 DB2 for AS/400 Database Programming V4R3

The following shows the DDS for a logical le that requires unique key values:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER TRANSACTION LOGICAL FILE (ORDFILL) A UNIQUE A R ORDHDR PFILE(ORDHDRP) A K ORDER A A R ORDDTL PFILE(ORDDTLP) A K ORDER A K LINE A

In this example, the contents of the key elds (the Order eld for the ORDHDR record format, and the Order and Line elds for the ORDDTL record format) must be unique whether the record is added through the ORDHDRP le, the ORDDTLP le, or the logical le dened here. With the Line eld specied as a second key eld in the ORDDTL record format, the same value can exist in the Order key eld in both physical les. Because the physical le ORDDTLP has two key elds and the physical le ORDHDRP has only one, the key values in the two les do not conict. Arranging Duplicate Keys: If you do not specify the UNIQUE keyword in DDS, you can specify how the system is to store records with duplicate key values, should they occur. You specify that records with duplicate key values are stored in the access path in one of the following ways: v Last-in-rst-out (LIFO). When the LIFO keyword is specied (1), records with duplicate key values are retrieved in last-in-rst-out order by the physical sequence of the records. Below is an example of DDS using the LIFO keyword.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDERP2 A 1 LIFO A R ORDER2 A . A . A . A K ORDER A

v First-in-rst-out (FIFO). If the FIFO keyword is specied, records with duplicate key values are retrieved in rst-in-rst-out order by the physical sequence of the records. v First-changed-rst-out (FCFO). If the FCFO keyword is specied, records with duplicate key values are retrieved in rst-changed-rst-out order by the physical sequence of the keys. v No specic order for duplicate key elds (the default). When the FIFO, FCFO, or LIFO keywords are not specied, no guaranteed order is specied for retrieving records with duplicate keys. No specic order for duplicate key elds allows more access path sharing, which can improve performance. For more information about access path sharing, see Using Existing Access Paths on page 51 . When a simple- or multiple-format logical le is based on more than one physical le member, records with duplicate key values are read in the order in which the les and members are specied on the DTAMBRS parameter on the Create Logical

Chapter 1. General Considerations

23

File (CRTLF) or Add Logical File Member (ADDLFM) command. Examples of logical les with more than one record format can be found in the DDS Reference book. The LIFO or FIFO order of records with duplicate key values is not determined by the sequence of updates made to the contents of the key elds, but solely by the physical sequence of the records in the le member. Assume that a physical le has the FIFO keyword specied (records with duplicate keys are in rst-in-rst-out order), and that the following shows the order in which records were added to the le:
Order Records Key Value Were Added to File 1 A 2 B 3 C 4 C 5 D

The sequence of the access path is (FIFO, ascending key):

Record Number 1 2 3 4 5 Key Value A B C C D

Records 3 and 4, which have duplicate key values, are in FIFO order. That is, because record 3 was added to the le before record 4, it is read before record 4. This would become apparent if the records were read in descending order. This could be done by creating a logical le based on this physical le, with the DESCEND keyword specied in the logical le. The sequence of the access path is (FIFO, descending key):
Record Number 5 3 4 2 1 Key Value D C C B A

If physical record 1 is changed such that the key value is C, the sequence of the access path for the physical le is (FIFO, ascending key):
Record Number 2 1 3 4 5 Key Value B C C C D

Finally, changing to descending order, the new sequence of the access path for the logical le is (FIFO, descending key):

24

OS/400 DB2 for AS/400 Database Programming V4R3

Record Number 5 1 3 4 2

Key Value D C C C B

After the change, record 1 does not appear after record 4, even though the contents of the key eld were updated after record 4 was added. The FCFO order of records with duplicate key values is determined by the sequence of updates made to the contents of the key elds. In the example above, after record 1 is changed such that the key value is C, the sequence of the access path (FCFO, ascending key only) is:
Record Number 2 3 4 1 5 Key Value B C C C D

For FCFO, the duplicate key ordering can change when the FCFO access path is rebuilt or when a rollback operation is performed. In some cases, your key eld can change but the physical key does not change. In these cases, the FCFO ordering does not change, even though the key eld has changed. For example, when the index ordering is changed to be based on the absolute value of the key, the FCFO ordering does not change. The physical value of the key does not change even though your key changes from negative to positive. Because the physical key does not change, FCFO ordering does not change. If the reuse deleted records attribute is specied for a physical le, the duplicate key ordering must be allowed to default or must be FCFO. The reuse deleted records attribute is not allowed for the physical le if either the key ordering for the le is FIFO or LIFO, or if any of the logical les dened over the physical le have duplicate key ordering of FIFO or LIFO.

Using Existing Access Path Specications

You can use the DDS keyword REFACCPTH to use another les access path specications. When the le is created, the system determines which access path to share. The le using the REFACCPTH keyword does not necessarily share the access path of the le specied in the REFACCPTH keyword. The REFACCPTH keyword is used to simply reduce the number of DDS statements that must be specied. That is, rather than code the key eld specications for the le, you can specify the REFACCPTH keyword. When the le is created, the system copies the key eld and select/omit specications from the le specied on the REFACCPTH keyword to the le being created.

Using Floating Point Fields in Access Paths

The collating sequence for records in a keyed database le depends on the presence of the SIGNED, UNSIGNED, and ABSVAL DDS keywords. For oating-point elds, the sign is the farthest left bit, the exponent is next, and the signicant is last. The collating sequence with UNSIGNED specied is:
Chapter 1. General Considerations

25

v Positive real numberspositive innity v Negative real numbersnegative innity A oating-point key eld with the SIGNED keyword specied, or defaulted to, on the DDS has an algebraic numeric sequence. The collating sequence is negative innityreal numberspositive innity. A oating-point key eld with the ABSVAL keyword specied on the DDS has an absolute value numeric sequence. The following oating-point collating sequences are observed: v Zero (positive or negative) collates in the same manner as any other positive/negative real number. v Negative zero collates before positive zero for SIGNED sequences. v Negative and positive zero collate the same for ABSVAL sequences. You cannot use not-a-number (*NAN) values in key elds. If you attempt this, and a *NAN value is detected in a key eld during le creation, the le is not created.

Protecting and Monitoring Your Database Data

The system provides two features to improve the integrity and consistency of your data. v Referential constraints let you put controls (constraints) on data in les you dene as having a mutual dependency. A referential constraint lets you specify rules to be followed when changes are made to les with constraints. Constraints are described in detail in Chapter 16. Referential Integrity. v Triggers let you run your own program to take any action or evaluate changes when les are changed. When predened changes are made or attempted, a trigger program is run. Triggers are described in detail in Chapter 17. Triggers.

Database File Creation: Introduction

The system supports several methods for creating a database le: v OS/400 IDDU v Structured Query Language v OS/400 control language (CL) You can create a database le using IDDU. If you are using IDDU to describe your database les, you might also consider using it to create your les. You can create a database le using SQL statements. SQL is the IBM relational database language, and can be used on AS/400 to interactively describe and create database les. You can also create a database le using CL. The CL database le create commands are: Create Physical File (CRTPF), Create Logical File (CRTLF), and Create Source Physical File (CRTSRCPF). Because additional system functions are available with CL, this guide focuses on creating les using CL.

26

OS/400 DB2 for AS/400 Database Programming V4R3

Database File and Member Attributes: Introduction

When you create a database le, database attributes are stored with the le and members. You specify attributes with database command parameters. For discussions on specifying these attributes and their possible values, see the CRTPF, CRTLF, CRTSRCPF, ADDPFM, ADDLFM, CHGPF, CHGLF, CHGPFM, CHGSRCPF, and CHGLFM commands in the CL Reference (Abridged) book.

File Name and Member Name (FILE and MBR) Parameters

You name a le with the FILE parameter in the create command. You also name the library in which the le will reside. When you create a physical or logical le, the system normally creates a member with the same name as the le. You can, however, specify a member name with the MBR parameter in the create commands. You can also choose not to create any members by specifying MBR(*NONE) in the create command. Note: The system does not automatically create a member for a source physical le.

Physical File Member Control (DTAMBRS) Parameter

You can control the reading of the physical le members with the DTAMBRS parameter of the Create Logical File (CRTLF) command. You can specify: v The order in which the physical le members are to be read. v The number of physical le members to be used. For more information about using logical les in this way, see Logical File Members on page 58.

Source File and Source Member (SRCFILE and SRCMBR) Parameters

The SRCFILE and SRCMBR parameters specify the names of the source le and members containing the DDS statements that describe the le being created. If you do not specify a name: v The default source le name is QDDSSRC. v The default member name is the name specied on the FILE parameter.

Database File Type (FILETYPE) Parameter

A database le type is either data (*DATA) or source (*SRC). The Create Physical File (CRTPF) and Create Logical File (CRTLF) commands use the default data le type (*DATA).

Maximum Number of Members Allowed (MAXMBRS) Parameter

The MAXMBRS parameter species the maximum number of members the le can hold. The default maximum number of members for physical and logical les is one, and the default for source physical les is *NOMAX.
Chapter 1. General Considerations

27

Where to Store the Data (UNIT) Parameter

Note: Effective for Version 3 Release 6 the UNIT parameter is a no-operation (NOP) function for the following commands: v CRTPF v CRTLF v CRTSRCPF v CHGPF v CHGLF v CHGSRCPF The parameter can still be coded; its presence will not cause an error. It will be ignored. The system nds a place for the le on auxiliary storage. To specify where to store the le, use the UNIT parameter. The UNIT parameter species: v The location of data records in physical les. v The access path for both physical les and logical les. The data is placed on different units if: v There is not enough space on the unit. v The unit is not valid for your system. An informational message indicating that the le was not placed on the requested unit is sent when le members are added. (A message is not sent when the le member is extended.)

Unit Parameter Tips

In general, you should not specify the UNIT parameter. Let the system place the le on the disk unit of its choosing. This is usually better for performance, and relieves you of the task of managing auxiliary storage. If you specify a unit number and also an auxiliary storage pool, the unit number is ignored. For more information about auxiliary storage pools, see the Backup and Recovery book.

Frequency of Writing Data to Auxiliary Storage (FRCRATIO) Parameter

You can control when database changes are written to auxiliary storage using the force write ratio (FRCRATIO) parameter on either the create, change, or override database le commands. Normally, the system determines when to write changed data from main storage to auxiliary storage. Closing the le (except for a shared close) and the force-end-of-data operation forces remaining updates, deletions, and additions to auxiliary storage. If you are journaling the le, the FRCRATIO parameter should normally be *NONE.

FRCRATIO Parameter Tip

Using the FRCRATIO parameter has performance and recovery considerations for your system. To understand these considerations, see Chapter 13. Database Recovery Considerations.

28

OS/400 DB2 for AS/400 Database Programming V4R3

Frequency of Writing the Access Path (FRCACCPTH) Parameter

The force access path (FRCACCPTH) parameter controls when an access path is written to auxiliary storage. FRCACCPTH(*YES) forces the access path to auxiliary storage whenever the access path is changed. This reduces the chance that the access path will need to be rebuilt should the system fail.

FRCACCPTH Parameter Tips

Specifying FRCACCPTH(*YES) can degrade performance when changes occur to the access path. An alternative to forcing the access path is journaling the access path. For more information about forcing access paths and journaling access paths, see Chapter 13. Database Recovery Considerations.

Check for Record Format Description Changes (LVLCHK) Parameter

When the le is opened, the system checks for changes to the database le denition. When the le changes to an extent that your program may not be able to process the le, the system noties your program. The default is to do level checking. You can specify if you want level checking when you: v Create a le. v Use a change database le command. You can override the system and ignore the level check using the Override with Database File (OVRDBF) command.

Level Check Example

For example, assume you compiled your program two months ago and, at that time, the le the program was dened as having three elds in each record. Last week another programmer decided to add a new eld to the record format, so that now each record would have four elds. The system noties your program, when it tries to open the le, that a signicant change occurred to the denition of the le since the last time the program was compiled. This notication is known as a record format level check.

Current Access Path Maintenance (MAINT) Parameter

The MAINT parameter species how access paths are maintained for closed les. While a le is open, the system maintains the access paths as changes are made to the data in the le. However, because more than one access path can exist for the same data, changing data in one le might cause changes to be made in access paths for other les that are not currently open (in use). The three ways of maintaining access paths of closed les are: v Immediate maintenance of an access path means that the access path is maintained as changes are made to its associated data, regardless if the le is open. Access paths used by referential constraints will always be in immediate maintenance. v Rebuild maintenance of an access path means that the access path is only maintained while the le is open, not when the le is closed; the access path is rebuilt when the le is opened the next time. When a le with rebuild maintenance is closed, the system stops maintaining the access path. When the
Chapter 1. General Considerations

29

le is opened again, the access path is totally rebuilt. If one or more programs has opened a specic le member with rebuild maintenance specied, the system maintains the access path for that member until the last user closes the le member. v Delayed maintenance of an access path means that any maintenance for the access path is done after the le member is opened the next time and while it remains open. However, the access path is not rebuilt as it is with rebuild maintenance. Updates to the access path are collected from the time the member is closed until it is opened again. When it is opened, only the collected changes are merged into the access path. If you do not specify the type of maintenance for a le, the default is immediate maintenance.

MAINT Parameter Comparison

Table 1 compares immediate, rebuild, and delayed maintenance as they affect opening and processing les.
Table 1. MAINT Values Function Open Immediate Maintenance Fast open because the access path is current. Rebuild Maintenance Slow open because access path must be rebuilt. Delayed Maintenance Moderately fast open because the access path does not have to be rebuilt, but it must still be changed. Slow open if extensive changes are needed. Moderately fast update/output operations when many access paths with delayed maintenance are built over changing data and are not open, (the system records the changes, but the access path itself is not maintained).

Process

Slower update/output operations when many access paths with immediate maintenance are built over changing data (the system must maintain the access paths).

Faster update/output operations when many access paths with rebuild maintenance are built over changing data and are not open (the system does not have to maintain the access paths).

Note: 1. Delayed or rebuild maintenance cannot be specied for a le that has unique keys. 2. Rebuild maintenance cannot be specied for a le if its access path is being journaled.

MAINT Parameter Tips

The type of access path maintenance to specify depends on the number of records and the frequency of additions, deletions, and updates to a le while the le is closed.

30

OS/400 DB2 for AS/400 Database Programming V4R3

You should use delayed maintenance for les that have relatively few changes to the access path while the le members are closed. Delayed maintenance reduces system overhead by reducing the number of access paths that are maintained immediately. It may also result in faster open processing, because the access paths do not have to be rebuilt. You may want to specify immediate maintenance for access paths that are used frequently, or when you cannot wait for an access path to be rebuilt when the le is opened. You may want to specify delayed maintenance for access paths that are not used frequently, if infrequent changes are made to the record keys that make up the access path. In general, for les used interactively, immediate maintenance results in good response time. For les used in batch jobs, either immediate, delayed, or rebuild maintenance is adequate, depending on the size of the members and the frequency of changes.

Access Path Recovery (RECOVER) Parameter

After a failure, changed access paths that were not forced to auxiliary storage or journaled cannot be used until they are rebuilt. The RECOVER parameter on the Create Physical File (CRTPF), the Create Logical File (CRTLF), and the Create Source Physical File (CRTSRCPF) commands species when that access path is to be rebuilt. Access paths are rebuilt either during the initial program load (IPL), after the IPL, or when a le is opened. Table 2 shows your choices for possible combinations of duplicate key and maintenance options.
Table 2. Recovery Options With This Duplicate Key Option Unique And This Maintenance Option Your Recovery Options Are Immediate Rebuild during the IPL (*IPL) Rebuild after the IPL (*AFTIPL, default) Do not rebuild at IPL, wait for rst open (*NO) Rebuild during the IPL (*IPL) Rebuild after the IPL (*AFTIPL) Do not rebuild at IPL, wait for rst open (*NO, default) Do not rebuild at IPL, wait for rst open (*NO, default)

Not unique

Immediate or delayed Rebuild

Not unique

RECOVER Parameter Tip

A list of les that have access paths that need to be recovered is shown on the Edit Rebuild of Access Paths display during the next initial program load (IPL) if the IPL is in manual mode. You can edit the original recovery option for the le by selecting the desired option on the display. After the IPL is complete, you can use the Edit Rebuild of Access Paths (EDTRBDAP) command to set the sequence in which access paths are rebuilt. If the IPL is unattended, the Edit Rebuild of Access Paths display is not shown and the access paths are rebuilt in the order determined by the RECOVER parameter. You only see the *AFTIPL and *NO (open) access paths.

Chapter 1. General Considerations

31

File Sharing (SHARE) Parameter

The database system lets multiple users access and change a le at the same time. The SHARE parameter allows sharing of opened les in the same job. For example, sharing a le in a job allows programs in the job to share a les status, record position, and buffer. Sharing les in a job can improve performance by reducing: v The amount of storage the job needs. v The time required to open and close the le. For more information about sharing les in the same job, see Sharing Database Files in the Same Job or Activation Group on page 104.

Locked File or Record Wait Time (WAITFILE and WAITRCD) Parameters

When you create a le, you can specify how long a program should wait for either the le or a record in the le if another job has the le or record locked. If the wait time ends before the le or record is released, a message is sent to the program indicating that the job was not able to use the le or read the record. For more information about record and le locks and wait times, see Record Locks on page 103 and File Locks on page 104.

Public Authority (AUT) Parameter

When you create a le, you can specify public authority. Public authority is the authority a user has to a le (or other object on the system) if that user does not have specic authority for the le or does not belong to a group with specic authority for the le. For more information about public authority, see Public Authority on page 91.

System on Which the File Is Created (SYSTEM) Parameter

You can specify if the le is to be created on the local system or a remote system that supports distributed data management (DDM). For more information about DDM, see the Distributed Data Management book.

File and Member Text (TEXT) Parameter

You can specify a text description for each le and member you create. The text data is useful in describing information about your le and members.

Coded Character Set Identier (CCSID) Parameter

You can specify a coded character set identier (CCSID) for physical les. The CCSID describes the encoding scheme and the character set for character type elds contained in this le. For more information about CCSIDs, see the National Language Support book.

32

OS/400 DB2 for AS/400 Database Programming V4R3

Sort Sequence (SRTSEQ) Parameter

You can specify the sort sequence for a le. The values of the SRTSEQ parameter along with the CCSID and LANGID parameters determine which sort sequence table the le uses. You can set the SETSEQ parameter for both the physical and the logical les. You can specify: v System supplied sort sequence tables with unique or shared collating weights. There are sort sequence tables for each supported language. v Any user-created sort sequence table. v The hexadecimal value of the characters in the character set. v The sort sequence of the current job or the one specied in the ALTSEQ parameter. The sort sequence table is stored with the le, except when the sort sequence is *HEX.

Language Identier (LANGID) Parameter

You can specify the language identier that the system should use when the SRTSEQ parameter value is *LANGIDSHR or *LANGIDUNQ. The values of the LANGID, CCSID, and SRTSEQ parameters determine which sort sequence table the le uses. You can set the LANGID parameter for physical and logical les. You can specify any language identier supported on your system, or you can specify that the language identier for the current job be used.

Chapter 1. General Considerations

33

34

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 2. Setting Up Physical Files

This chapter discusses some of the unique considerations for describing, then creating, a physical le. For information about describing a physical le record format, see Example of Describing a Physical File Using DDS on page 7. For information about describing a physical le access path, refer to Describing the Access Path for the File on page 17.

Creating a Physical File

To create a physical le, take the following steps: 1. If you are using DDS, enter DDS for the physical le into a source le. This can be done using the AS/400 Application Development Tools source entry utility (SEU). See Working with Source Files on page 228, for more information about how source statements are entered in source les. 2. Create the physical le. You can use the Create Physical File (CRTPF) command, or the Create Source Physical File (CRTSRCPF) command. The following command creates a one-member le using DDS and places it in a library called DSTPRODLB.
CRTPF FILE(DSTPRODLB/ORDHDRP) TEXT('Order header physical file')

As shown, this command uses defaults. For the SRCFILE and SRCMBR parameters, the system uses DDS in the source le called QDDSSRC and the member named ORDHDRP (the same as the le name). The le ORDHDRP with one member of the same name is placed in the library DSTPRODLB.

Specifying Physical File and Member Attributes

Some of the attributes you can specify for physical les and members on the Create Physical File (CRTPF), Create Source Physical File (CRTSRCPF), Change Physical File (CHGPF), Change Source Physical File (CHGSRCPF), Add Physical File Member (ADDPFM), and Change Physical File Member (CHGPFM) commands include (command names are given in parentheses):

Expiration Date
EXPDATE Parameter. This parameter species an expiration date for each member in the le (ADDPFM, CHGPFM, CRTPF, CHGPF, CRTSRCPF, and CHGSRCPF commands). If the expiration date is past, the system operator is notied when the le is opened. The system operator can then override the expiration date and continue, or stop the job. Each member can have a different expiration date, which is specied when the member is added to the le. (The expiration date check can be overridden; see Checking for the Expiration Date of the File on page 102.)

Copyright IBM Corp. 1997, 1998

35

Size of the Physical File Member

SIZE Parameter. This parameter species the maximum number of records that can be placed in each member (CRTPF, CHGPF, CRTSRCPF, AND CHGSRCPF commands). The following formula can be used to determine the maximum: R + (I * N) where: R I N is the starting record count is the number of records (increment) to add each time is the number of times to add the increment

The defaults for the SIZE parameter are: R I N 10,000 1,000 3 (CRTPF command) 499 (CRTSRCPF command) For example, assume that R is a le created for 5000 records plus 3 increments of 1000 records each. The system can add 1000 to the initial record count of 5000 three times to make the total maximum 8000. When the total maximum is reached, the system operator either stops the job or tells the system to add another increment of records and continue. When increments are added, a message is sent to the system history log. When the le is extended beyond its maximum size, the minimum extension is 10% of the current size, even if this is larger than the specied increment. Instead of taking the default size or specifying a size, you can specify *NOMAX. For information about the maximum number of records allowed in a le, see Appendix A. Database File Sizes.

Storage Allocation
ALLOCATE Parameter. This parameter controls the storage allocated for members when they are added to the le (CRTPF, CHGPF, CRTSRCPF, and CHGSRCPF commands). The storage allocated would be large enough to contain the initial record count for a member. If you do not allocate storage when the members are added, the system will automatically extend the storage allocation as needed. You can use the ALLOCATE parameter only if you specied a maximum size on the SIZE parameter. If SIZE(*NOMAX) is specied, then ALLOCATE(*YES) cannot be specied.

Method of Allocating Storage

CONTIG Parameter. This parameter controls the method of allocating physical storage for a member (CRTPF and CRTSRCPF commands). If you allocate storage, you can request that the storage for the starting record count for a member be contiguous. That is, all the records in a member are to physically reside together. If

36

OS/400 DB2 for AS/400 Database Programming V4R3

there is not enough contiguous storage, contiguous storage allocation is not used and an informational message is sent to the job that requests the allocation, at the time the member is added. Note: When a physical le is rst created, the system always tries to allocate its initial storage contiguously. The only difference between using CONTIG(*NO) and CONTIG(*YES) is that with CONTIG(*YES) the system sends a message to the job log if it is unable to allocate contiguous storage when the le is created. No message is sent when a le is extended after creation, regardless of what you specied on the CONTIG parameter.

Record Length
RCDLEN Parameter. This parameter species the length of records in the le (CRTPF and CRTSRCPF commands). If the le is described to the record level only, then you specify the RCDLEN parameter when the le is created. This parameter cannot be specied if the le is described using DDS, IDDU, or SQL (the system automatically determines the length of records in the le from the eld level descriptions).

Deleted Records
DLTPCT Parameter. This parameter species the percentage of deleted records a le can contain before you want the system to send a message to the system history log (CRTPF, CHGPF, CRTSRCPF, and CHGSRCPF commands). When a le is closed, the system checks the member to determine the percentage of deleted records. If the percentage exceeds that value specied in the DLTPCT parameter, a message is sent to the history log. (For information about processing the history log, see the chapter on message handling in the CL Programming book.) One reason you might want to know when a le reaches a certain percentage of deleted records is to reclaim the space used by the deleted records. After you receive the message about deleted records, you could run the Reorganize Physical File Member (RGZPFM) command to reclaim the space. (For more information about RGZPFM, see Reorganizing Data in Physical File Members on page 195.) You can also specify to bypass the deleted records check by using the *NONE value for the DLTPCT parameter. *NONE is the default for the DLTPCT parameter. REUSEDLT Parameter. This parameter species whether deleted record space should be reused on subsequent write operations (CRTPF and CHGPF commands). When you specify *YES for the REUSEDLT parameter, all insert requests on that le try to reuse deleted record space. Reusing deleted record space allows you to reclaim space used by deleted records without having to issue a RGZPFM command. When the CHGPF command is used to change a le to reuse deleted records, the command could take a long time to run, especially if the le is large and there are already a lot of deleted records in it. It is important to note the following: v The term arrival order loses its meaning for a le that reuses deleted record space. Records are no longer always inserted at the end of the le when deleted record space is reused. v If a new physical le is created with the reuse deleted record space attribute and the le is keyed, the FIFO or LIFO access path attribute cannot be specied for the physical le, nor can any keyed logical le with the FIFO or LIFO access path attribute be built over the physical le.

Chapter 2. Setting Up Physical Files

37

v You cannot change an existing physical le to reuse deleted record space if there are any logical les over the physical le that specify FIFO or LIFO ordering for duplicate keys, or if the physical le has a FIFO or LIFO duplicate key ordering. v Reusing deleted record space should not be specied for a le that is processed as a direct le or if the le is processed using relative record numbers. Note: See Reusing Deleted Records on page 99 for more information on reusing deleted records. *NO is the default for the REUSEDLT parameter.

Physical File Capabilities

ALWUPD and ALWDLT Parameters. File capabilities are used to control which input/output operations are allowed for a database le independent of database le authority. For more information about database le capabilities and authority, see Chapter 4. Database Security.

Source Type
SRCTYPE Parameter. This parameter species the source type for a member in a source le (ADDPFM and CHGPFM commands). The source type determines the syntax checker, prompting, and formatting that are used for the member. If the user species a unique source type (other than AS/400 supported types like COBOL and RPG), the user must provide the programming to handle the unique type. If the source type is changed, it is only reected when the member is subsequently opened; members currently open are not affected.

38

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 3. Setting Up Logical Files

This chapter discusses some of the unique considerations for describing, then creating, a logical le. Many of the rules for setting up logical les apply to all categories of logical les. In this guide, rules that apply only to one category of logical le identify which category they refer to. Rules that apply to all categories of logical les do not identify the specic categories they apply to.

Describing Logical File Record Formats

For every logical le record format described with DDS, you must specify a record format name and either the PFILE keyword (for simple and multiple format logical les), or the JFILE keyword (for join logical les). The le names specied on the PFILE or JFILE keyword are the physical les that the logical le is based on. A simple or multiple-format logical le record format can be specied with DDS in any one of the following ways: 1. In the simple logical le record format, specify only the record format name and the PFILE keyword. The record format for the only (or rst) physical le specied on the PFILE keyword is the record format for the logical le. The record format name specied in the logical le must be the same as the record format name in the only (or rst) physical le.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A A R ORDDTL PFILE(ORDDTLP) A

Figure 8. Simple Logical File

2. In the following example, you describe your own record format by listing the eld names you want to include. You can specify the eld names in a different order, rename elds using the RENAME keyword, combine elds using the CONCAT keyword, and use specic positions of a eld using the SST keyword. You can also override attributes of the elds by specifying different attributes in the logical le.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A A R ORDHDR PFILE(ORDHDRP) A ORDER A CUST A SHPVIA A

Figure 9. Simple Logical File with Fields Specied

3. In the following example, the le name specied on the FORMAT keyword is the name of a database le. The record format is shared from this database le by the logical le being described. The le name can be qualied by a library name. If a library name is not specied, the library list is used to nd the le. The le must exist when the le you are describing is created. In addition, the

Copyright IBM Corp. 1997, 1998

39

record format name you specify in the logical le must be the same as one of the record format names in the le you specify on the FORMAT keyword.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A A R CUSRCD PFILE(CUSMSTP) A FORMAT(CUSMSTL) A

In the following example, a program needs: v The elds placed in a different order v A subset of the elds from the physical le v The data types changed for some elds v The eld lengths changed for some elds You can use a logical le to make these changes.
Logical File FIELD D FIELD A FIELD C Data type: Data type: Data type: Zoned decimal Zoned decimal Zoned decimal Length: 10,0 Length: 8,2 Length: 5,0 Physical File FIELD A FIELD B FIELD C FIELD D Data type: Data type: Data type: Data type: Zoned decimal Character Binary Character Length: 8,2 Length: 32 Length: 2,0 Length: 10

For the logical le, the DDS would be:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A A R LOGREC PFILE(PF1) A D 10S 0 A A A C 5S 0 A

For the physical le, the DDS would be:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A A R PHYREC A A 8S 2 A B 32 A C 2B 0 A D 10 A

When a record is read from the logical le, the elds from the physical le are changed to match the logical le description. If the program updates or adds a

40

OS/400 DB2 for AS/400 Database Programming V4R3

record, the elds are changed back. For an add or update operation using a logical le, the program must supply data that conforms with the format used by the logical le. The following chart shows what types of data mapping are valid between physical and logical les.
Logical File Data Type Physical File Data Type Character or Hexadecimal Zoned Packed Binary Floating Point Date Time Time Stamp Notes: 1. Valid only if the number of characters or bytes equals the number of digits. 2. Valid only if the binary eld has zero decimal positions. 3. Valid only if both binary elds have the same number of decimal positions. Character or Hexadecimal Zoned Valid See Note 1 Not valid Not valid Not valid Not valid Not valid Not valid See Note 1 Valid Valid See Note 2 Valid Valid Valid Not valid Packed Not valid Valid Valid See Note 2 Valid Not valid Not valid Not valid Binary Not valid See Note 2 See Note 2 See Note 3 See Note 2 Not valid Not valid Not valid Floating Point Not valid Valid Valid See Note 2 Valid Not valid Not valid Not valid Date Not valid Not valid Not valid Not valid Not valid Valid Not valid Valid Time Not valid Not valid Not valid Not valid Not valid Not valid Valid Valid Timestamp Not valid Not Valid Not valid Not valid Not valid Not valid Not valid Valid

Note: For information about mapping DBCS elds, see Appendix B. Double-Byte Character Set (DBCS) Considerations.

Describing Field Use for Logical Files

You can specify that elds in database les are to be input-only, both (input/output), or neither elds. Do this by specifying one of the following in position 38: Entry Meaning

Blank For simple or multiple format logical les, defaults to B (both) For join logical les, defaults to I (input only) B I N Both input and output allowed; not valid for join logical les Input only (read only) Neither input nor output; valid only for join logical les

Chapter 3. Setting Up Logical Files

41

Note: The usage value (in position 38) is not used on a reference function. When another le refers to a eld (using a REF or REFFLD keyword) in a logical le, the usage value is not copied into that le.

Both
A both eld can be used for both input and output operations. Your program can read data from the eld and write data to the eld. Both elds are not valid for join logical les, because join logical les are read-only les.

Input Only
An input only eld can be used for read operations only. Your program can read data from the eld, but cannot update the eld in the le. Typical cases of input-only elds are key elds (to reduce maintenance of access paths by preventing changes to key eld values), sensitive elds that a user can see but not update (for example, salary), and elds for which either the translation table (TRNTBL) keyword or the substring (SST) keyword is specied. If your program updates a record in which you have specied input-only elds, the input-only elds are not changed in the le. If your program adds a record that has input-only elds, the input-only elds take default values (DFT keyword).

Neither
A neither eld is used neither for input nor for output. It is valid only for join logical les. A neither eld can be used as a join eld in a join logical le, but your program cannot read or update a neither eld. Use neither elds when the attributes of join elds in the physical les do not match. In this case, one or both join elds must be dened again. However, you cannot include these redened elds in the record format (the application program does not see the redened elds.) Therefore, redened join elds can be coded N so that they do not appear in the record format. A eld with N in position 38 does not appear in the buffer used by your program. However, the eld description is displayed with the Display File Field Description (DSPFFD) command. Neither elds cannot be used as select/omit or key elds. For an example of a neither eld, see Describing Fields That Never Appear in the Record Format (Example 5) on page 75.

Deriving New Fields from Existing Fields

Fields in a logical le can be derived from elds in the physical le the logical le is based on or from elds in the same logical le. For example, you can concatenate, using the CONCAT keyword, two or more elds from a physical le to make them appear as one eld in the logical le. Likewise, you can divide one eld in the physical le to make it appear as multiple elds in the logical le with the SST keyword.

42

OS/400 DB2 for AS/400 Database Programming V4R3

Concatenated Fields
Using the CONCAT keyword, you can combine two or more elds from a physical le record format to make one eld in a logical le record format. For example, a physical le record format contains the elds Month, Day, and Year. For a logical le, you concatenate these elds into one eld, Date. The eld length for the resulting concatenated eld is the sum of the lengths of the included elds (unless the elds in the physical le are binary or packed decimal, in which case they are changed to zoned decimal). The eld length of the resulting eld is automatically calculated by the system. A concatenated eld can have: v Column headings v Validity checking v Text description v Edit code or edit word (numeric concatenated elds only) Note: This editing and validity checking information is not used by the database management system but is retrieved when eld descriptions from the database le are referred to in a display or printer le. When elds are concatenated, the data types can change (the resulting data type is automatically determined by the system). The following rules and restrictions apply: v The OS/400 program assigns the data type based on the data types of the elds that are being concatenated. v The maximum length of a concatenated eld varies depending on the data type of the concatenated eld and the length of the elds being concatenated. If the concatenated eld is zoned decimal (S), its total length cannot exceed 31 bytes; if it is character (A), its total length cannot exceed 32 766 bytes. v In join logical les, the elds to be concatenated must be from the same physical le. The rst eld specied on the CONCAT keyword identies which physical le is to be used. The rst eld must, therefore, be unique among the physical les on which the logical le is based, or you must also specify the JREF keyword to specify which physical le to use. v The use of a concatenated eld must be I (input only) if the concatenated eld is variable length. Otherwise, the use may be B (both input and output). v REFSHIFT cannot be specied on a concatenated eld that has been assigned a data type of O or J. v If any of the elds contain the null value, the result of concatenation is the null value. Note: For information about concatenating DBCS elds, see Appendix B. Double-Byte Character Set (DBCS) Considerations. When only numeric elds are concatenated, the sign of the last eld in the group is used as the sign of the concatenated eld. Notes: 1. Numeric elds with decimal precision other than zero cannot be included in a concatenated eld. 2. Date, time, timestamp, and oating-point elds cannot be included in a concatenated eld.

Chapter 3. Setting Up Logical Files

43

The following shows the eld description in DDS for concatenation. (The CONCAT keyword is used to specify the elds to concatenate.)
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A 00101A MONTH 00102A DAY 00103A YEAR 00104A DATE CONCAT(MONTH DAY YEAR) A

In this example, the logical le record format includes the separate elds of Month, Day, and Year, as well as the concatenated Date eld. Any of the following can be used: v A format with the separate elds of Month, Day, and Year v A format with only the concatenated Date eld v A format with the separate elds Month, Day, Year and the concatenated Date eld When both separate and concatenated elds exist in the format, any updates to the elds are processed in the sequence in which the DDS is specied. In the previous example, if the Date eld contained 103188 and the Month eld is changed to 12, when the record is updated, the month in the Date eld would be used. The updated record would contain 103188. If the Date eld were specied rst, the updated record would contain 123188. Concatenated elds can also be used as key elds and select/omit elds.

Substring Fields
You can use the SST keyword to specify which elds (character, hexadecimal, or zoned decimal) are in a substring. (You can also use substring with a packed eld in a physical le by specifying S (zoned decimal) as the data type in the logical le.) For example, assume you dened the Date eld in physical le PF1 as 6 characters in length. You can describe the logical le with three elds, each 2 characters in length. You can use the SST keyword to dene MM as 2 characters starting in position 1 of the Date eld, DD as 2 characters starting in position 3 of the Date eld, and YY as 2 characters starting in position 5 of the Date eld. The following shows the eld descriptions in DDS for these substring elds. The SST keyword is used to specify the eld to substring.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 PFILE(PF1) A A MM I SST(DATE 1 2) A DD I SST(DATE 3 2) A YY I SST(DATE 5 2) A

Note that the starting position of the substring is specied according to its position in the eld being operated on (Date), not according to its position in the le. The I in the Usage column indicates input-only. Substring elds can also be used as key elds and select/omit elds.

44

OS/400 DB2 for AS/400 Database Programming V4R3

Renamed Fields
You can name a eld in a logical le differently than in a physical le using the RENAME keyword. You might want to rename a eld in a logical le because the program was written using a different eld name or because the original eld name does not conform to the naming restrictions of the high-level language you are using.

Translated Fields
You can specify a translation table for a eld using the TRNTBL keyword. When you read a logical le record and a translation table was specied for one or more elds in the logical le, the system translates the data from the eld value in the physical le to the value determined by the translation table.

Describing Floating-Point Fields in Logical Files

You can use oating-point elds as mapped elds in logical les. A single- or double-precision oating-point eld can be mapped to or from a zoned, packed, zero-precision binary, or another oating-point eld. You cannot map between a oating-point eld and a nonzero-precision binary eld, a character eld, a hexadecimal eld, or a DBCS eld. Mapping between oating-point elds of different precision, single or double, or between oating-point elds and other numeric elds, can result in rounding or a loss of precision. Mapping a double-precision oating-point number to a single-precision oating-point number can result in rounding, depending on the particular number involved and its internal representation. Rounding is to the nearest (even) bit. The result always contains as much precision as possible. A loss of precision can also occur between two decimal numbers if the number of digits of precision is decreased. You can inadvertently change the value of a eld which your program did not explicitly change. For oating-point elds, this can occur if a physical le has a double-precision eld that is mapped to a single-precision eld in a logical le, and you issue an update for the record through the logical le. If the internal representation of the oating-point number causes it to be rounded when it is mapped to the logical le, then the update of the logical record causes a permanent loss of precision in the physical le. If the rounded number is the key of the physical record, then the sequence of records in the physical le can also change. A xed-point numeric eld can also be updated inadvertently if the precision is decreased in the logical le.

Describing Access Paths for Logical Files

The access path for a logical le record format can be specied in one of the following ways: 1. Keyed sequence access path specication. Specify key elds after the last record or eld level specication. The key eld names must be in the record format. For join logical les, the key elds must come from the rst, or primary, physical le.

Chapter 3. Setting Up Logical Files

45

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R CUSRCD PFILE(CUSMSTP) A K ARBAL A K CRDLMT A | |

2. Encoded vector access path specication. You dene the encoded vector access path with the SQL CREATE INDEX statement. 3. Arrival sequence access path specication. Specify no key elds. You can specify only one physical le on the PFILE keyword (and only one of the physical les members when you add the logical le member).
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R CUSRCD PFILE(CUSMSTP)

4. Previously dened keyed-sequence access path specication (for simple and multiple format logical les only). Specify the REFACCPTH keyword at the le level to identify a previously created database le whose access path and select/omit specications are to be copied to this logical le. You cannot specify individual key or select/omit elds with the REFACCPTH keyword. Note: Even though the specied les access path specications are used, the system determines which les access path, if any, will actually be shared. The system always tries to share access paths, regardless of whether the REFACCPTH keyword is used.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 REFACCPTH(DSTPRODLIB/ORDHDRL) A R CUSRCD PFILE(CUSMSTP)

When you dene a record format for a logical le that shares key eld specications of another les access path (using the DDS keyword, REFACCPTH), you can use any elds from the associated physical le record format. These elds do not have to be used in the le that describes the access path. However, all key and select/omit elds used in the le that describes the access path must be used in the new record format.

Selecting and Omitting Records Using Logical Files

The system can select and omit records when using a logical le. This can help you to exclude records in a le for processing convenience or for security. The process of selecting and omitting records is based on comparisons identied in position 17 of the DDS Form for the logical le, and is similar to a series of comparisons coded in a high-level language program. For example, in a logical le that contains order detail records, you can specify that the only records you want to use are those in which the quantity ordered is greater than the quantity shipped. All other records are omitted from the access path. The omitted records remain in the physical le but are not retrieved for the logical le. If you are adding records to the physical le, all records are added, but only selected records that match the select/omit criteria can be retrieved using the select/omit access path.

46

OS/400 DB2 for AS/400 Database Programming V4R3

In DDS, to specify select or omit, you specify an S (select) or O (omit) in position 17 of the DDS Form. You then name the eld (in positions 19 through 28) that will be used in the selection or omission process. In positions 45 through 80 you specify the comparison. Note: Select/omit specications appear after key specications (if keys are specied). Records can be selected and omitted by several types of comparisons: v VALUES. The contents of the eld are compared to a list of not more than 100 values. If a match is found, the record is selected or omitted. In the following example, a record is selected if one of the values specied in the VALUES keyword is found in the Itmnbr eld.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A S ITMNBR VALUES(301542 306902 382101 422109 + A 431652 486592 502356 556608 590307) A

v RANGE. The contents of the eld are compared to lower and upper limits. If the contents are greater than or equal to the lower limit and less than or equal to the upper limit, the record is selected or omitted. In the following example, all records with a range 301000 through 599999 in the Itmnbr eld are selected.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A S ITMNBR RANGE(301000 599999) A

v CMP. The contents of a eld are compared to a value or the contents of another eld. Valid comparison codes are EQ, NE, LT, NL, GT, NG, LE, and GE. If the comparison is met, the record is selected or omitted. In the following example, a record is selected if its Itmnbr eld is less than or equal to 599999:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A S ITMNBR CMP(LE 599999) A

The value for a numeric eld for which the CMP, VALUES, or RANGE keyword is specied is aligned based on the decimal positions specied for the eld and lled with zeros where necessary. If decimal positions were not specied for the eld, the decimal point is placed to the right of the farthest right digit in the value. For example, for a numeric eld with length 5 and decimal position 2, the value 1.2 is interpreted as 001.20 and the value 100 is interpreted as 100.00. The status of a record is determined by evaluating select/omit statements in the sequence you specify them. If a record qualies for selection or omission, subsequent statements are ignored. Normally the select and omit comparisons are treated independently from one another; the comparisons are ORed together. That is, if the select or omit comparison is met, the record is either selected or omitted. If the condition is not met, the system proceeds to the next comparison. To connect comparisons together, you simply leave a space in position 17 of the DDS Form. Then, all the comparisons that were connected in this fashion must be met before the record is selected or omitted. That is, the comparisons are ANDed together.

Chapter 3. Setting Up Logical Files

47

The fewer comparisons, the more efficient the task is. So, when you have several select/omit comparisons, try to specify the one that selects or omits the most records rst. In the following examples, few records exist for which the Rep eld is JSMITH. The examples show how to use DDS to select all the records before 1988 for a sales representative named JSMITH in the state of New York. All give the same results with different efficiency (in this example, 3 is the most efficient).
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A S ST CMP(EQ 'NY') 1 A REP CMP(EQ 'JSMITH') A YEAR CMP(LT 88) A |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A O YEAR CMP(GE 88) 2 A S ST CMP(EQ 'NY') A REP CMP(EQ 'JSMITH') A |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A O REP CMP(NE 'JSMITH') 3 A O ST CMP(NE 'NY') A S YEAR CMP(LT 88) A

Figure 10. Three Ways to Code Select/Omit Function

1 2 3

All records must be compared with all of the select elds St, Rep, and Year before they can be selected or omitted. All records are compared with the Year eld. Then, the records before 1988 have to be compared with the St and Rep elds. All records are compared with the Rep eld. Then, only the few for JSMITH are compared with the St eld. Then, the few records that are left are compared to the Year eld.

As another example, assume that you want to select the following: v All records for departments other than Department 12. v Only those records for Department 12 that contain an item number 112505, 428707, or 480100. No other records for Department 12 are to be selected. If you create the preceding example with a sort sequence table, the select/omit elds are translated according to the sort table before the comparison. For example, with a sort sequence table using shared weightings for uppercase and lowercase, NY and ny are equal. For details, see the DDS Reference. The following diagram shows the logic included in this example:

48

OS/400 DB2 for AS/400 Database Programming V4R3

** Start ) ** * Dept * Yes number not = > Select * 12 * * * * * * * * * * * * Item * Yes number = * * 112505 * * * * * * No * * * * * * Item * Yes number = * * 428707 * * * * * * No * * * * * * Item * Yes number = * * 480100 * * * * * * No * * * * *

<

Omit

The following shows how to code this example using the DDS select and omit functions:

Chapter 3. Setting Up Logical Files

49

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A S DPTNBR CMP(NE 12) A S ITMNBR VALUES(112505 428707 480100) A

It is possible to have an access path with select/omit values and process the le in arrival sequence. For example, a high-level language program can specify that the keyed access path is to be ignored. In this case, every record is read from the le in arrival sequence, but only those records meeting the select/omit values specied in the le are returned to the high-level language program. A logical le with key elds and select/omit values specied can be processed in arrival sequence or using relative record numbers randomly. Records omitted by the select/omit values are not processed. That is, if an omitted record is requested by relative record number, the record is not returned to the high-level language program. The system does not ensure that any additions or changes through a logical le will allow the record to be accessed again in the same logical le. For example, if the selection values of the logical le species only records with an A in Fld1 and the program updates the record with a B in Fld1, the program cannot retrieve the record again using this logical le. Note: You cannot select or omit based on the values of a oating-point eld. The two kinds of select/omit operations are: access path select/omit and dynamic select/omit. The default is access path select/omit. The select/omit specications themselves are the same in each kind, but the system actually does the work of selecting and omitting records at different times.

Access Path Select/Omit

With access path select/omit, the access path only contains keys that meet the select/omit values specied for the logical le. When you specify key elds for a le, an access path is kept for the le and maintained by the system when you add or update records in the physical le(s) used by the logical le. The only index entries in the access path are those that meet the select/omit values.

Dynamic Select/Omit
With dynamic select/omit, when a program reads records from the le, the system only returns those records that meet the select/omit values. That is, the actual select/omit processing is done when records are read by a program, rather than when the records are added or changed. However, the keyed sequence access path contains all the keys, not just keys from selected records. Access paths using dynamic select/omit allow more access path sharing, which can improve performance. For more information about access path sharing, see Using Existing Access Paths on page 51. To specify dynamic select/omit, use the dynamic selection (DYNSLT) keyword. With dynamic select/omit, key elds are not required. If you have a le that is updated frequently and read infrequently, you may not need to update the access path for select/omit purposes until your program reads the le. In this case, dynamic select/omit might be the correct choice. The following example helps describe this.

50

OS/400 DB2 for AS/400 Database Programming V4R3

You use a code eld (A=active, I=inactive), which is changed infrequently, to select/omit records. Your program processes the active records and the majority (over 80%) of the records are active. It can be more efficient to use DYNSLT to dynamically select records at processing time rather than perform access path maintenance when the code eld is changed.

Using the Open Query File Command to Select/Omit Records

Another method of selecting records is using the QRYSLT parameter on the Open Query File (OPNQRYF) command. The open data path created by the OPNQRYF command is like a temporary logical le; that is, it is automatically deleted when it is closed. A logical le, on the other hand, remains in existence until you specically delete it. For more details about the OPNQRYF command, see Using the Open Query File (OPNQRYF) Command on page 121.

Using Existing Access Paths

When two or more les are based on the same physical les and the same key elds in the same order, they automatically share the same keyed sequence access path. When access paths are shared, the amount of system activity required to maintain access paths and the amount of auxiliary storage used by the les is reduced. When a logical le with a keyed sequence access path is created, the system always tries to share an existing access path. For access path sharing to occur, an access path must exist on the system that satises the following conditions: v The logical le member to be added must be based on the same physical le members that the existing access path is based on. v The length, data type, and number of decimal positions specied for each key eld must be identical in both the new le and the existing le. v If the FIFO, LIFO, or FCFO keyword is not specied, the new le can have fewer key elds than the existing access paths. That is, a new logical le can share an existing access path if the beginning part of the key is identical. However, when a le shares a partial set of keys from an existing access path, any record updates made to elds that are part of the set of keys for the shared access path may change the record position in that access path. See Example of Implicitly Shared Access Paths on page 52 for a description of such a circumstance. v The attributes of the access path (such as UNIQUE, LIFO, FIFO, or FCFO) and the attributes of the key elds (such as DESCEND, ABSVAL, UNSIGNED, and SIGNED) must be identical. Exceptions: 1. A FIFO access path can share an access path in which the UNIQUE keyword is specied if all the other requirements for access path sharing are met. 2. A UNIQUE access path can share a FIFO access path that needs to be rebuilt (for example, has *REBLD maintenance specied), if all the other requirements for access path sharing are met. v If the new logical le has select/omit specications, they must be identical to the select/omit specications of the existing access path. However, if the new logical le species DYNSLT, it can share an existing access path if the existing access path has either: The dynamic select (DYNSLT) keyword specied No select/omit keywords specied
Chapter 3. Setting Up Logical Files

51

v The alternative collating sequence (ALTSEQ keyword) and the translation table (TRNTBL keyword) of the new logical le member, if any, must be identical to the alternative collating sequence and translation table of the existing access path. Note: Logical les that contain concatenated or substring elds cannot share access paths with physical les. The owner of any access path is the logical le member that originally created the access path. For a shared access path, if the logical member owning the access path is deleted, the rst member to share the access path becomes the new owner. The FRCACCPTH, MAINT, and RECOVER parameters on the Create Logical File (CRTLF) command need not match the same parameters on an existing access path for that access path to be shared. When an access path is shared by several logical le members, and the FRCACCPTH, MAINT, and RECOVER parameters are not identical, the system maintains the access path by the most restrictive value for each of the parameters specied by the sharing members. The following illustrates how this occurs:
MBRA specifies: FRCACCPTH(*NO) MAINT(*IMMED) RECOVER(*AFTIPL) MBRB specifies: System does: FRCACCPTH(*YES) FRCACCPTH(*YES) MAINT(*DLY) MAINT(*IMMED) RECOVER(*NO) RECOVER(*AFTIPL)

Access path sharing does not depend on sharing between members; therefore, it does not restrict the order in which members can be deleted. The Display File Description (DSPFD) and Display Database Relations (DSPDBR) commands show access path sharing relationships.

Example of Implicitly Shared Access Paths

The purpose of this example is help you fully understand implicit access path sharing. Two logical les, LFILE1 and LFILE2, are built over the physical le PFILE. LFILE1, which was created rst, has two key elds, KFD1 and KFD2. LFILE2 has three key elds, KFD1, KFD2, and KFD3. The two logical les use two of the same key elds, but no access path is shared because the logical le with three key elds was created after the le with two key elds.
Table 3. Physical and Logical Files Before Save and Restore Physical File (PFILE) Logical File 1 (LFILE1) Access Path KFD1, KFD2 Fields KFD1, KFD2, KFD3, A, KFD1, KFD2, KFD3, F, B, C, D, E, F, G C, A Logical File 2 (LFILE2) KFD1, KFD2, KFD3 KFD1, KFD2, KFD3, D, G, F, E

An application uses LFILE1 to access the records and to change the KFD3 eld to blank if it contains a C, and to a C if it is blank. This application causes the user no unexpected results because the access paths are not shared. However, after a save and restore of the physical le and both logical les, the program appears to do nothing and takes longer to process.

52

OS/400 DB2 for AS/400 Database Programming V4R3

Unless you do something to change the restoration, the AS/400 system: v Restores the logical le with the largest number of keys rst v Does not build unnecessary access paths See Controlling When Access Paths Are Rebuilt on page 218 for information on changing these conditions. Because it has three key elds, LFILE2 is restored rst. After recovery, LFILE1 implicitly shares the access path for LFILE2. Users who do not understand implicitly shared access paths do not realize that when they use LFILE1 after a recovery, they are really using the key for LFILE2.
Table 4. Physical and Logical Files After Save and Restore. Note that the only difference from before the save and restore is that the logical les now share the same access path. Physical File (PFILE) Access Path Fields KFD1, KFD2, KFD3, A, B, C, D, E, F, G Logical File 1 (LFILE1) KFD1, KFD2, KFD3 KFD1, KFD2, KFD3, F, C, A Logical File 2 (LFILE2) KFD1, KFD2, KFD3 KFD1, KFD2, KFD3, D, G, F, E

The records to be tested and changed contain:

Relative Record 001 002 003 004 KFD1 01 01 01 01 KFD2 01 01 01 01 KFD3 <blank> <blank> <blank> <blank>

The rst record is read via the rst key of 0101<blank> and changed to 0101C. The records now look like:
Relative Record 001 002 003 004 KFD1 01 01 01 01 KFD2 01 01 01 01 KFD3 C <blank> <blank> <blank>

When the application issues a get next key, the next higher key above 0101<blank> is 0101C. This is the record that was just changed. However, this time the application changes the KFD3 eld from C to blank. Because the user does not understand implicit access path sharing, the application accesses and changes every record twice. The end result is that the application takes longer to run, and the records look like they have not changed.

Creating a Logical File

Before creating a logical le, the physical le or les on which the logical le is based must already exist. To create a logical le, take the following steps: 1. Type the DDS for the logical le into a source le. This can be done using SEU or another method. See Working with Source Files on page 228, for how
Chapter 3. Setting Up Logical Files

53

source is placed in source les. The following shows the DDS for logical le ORDHDRL (an order header le):
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER HEADER LOGICAL FILE (ORDHDRL) A R ORDHDR PFILE(ORDHDRP) A K ORDER

This le uses the key eld Order (order number) to dene the access path. The record format is the same as the associated physical le ORDHDRP. The record format name for the logical le must be the same as the record format name in the physical le because no eld descriptions are given. 2. Create the logical le. You can use the Create Logical File (CRTLF) command. The following shows how the CRTLF command could be typed:
CRTLF FILE(DSTPRODLB/ORDHDRL) TEXT('Order header logical file')

As shown, this command uses some defaults. For example, because the SRCFILE and SRCMBR parameters are not specied, the system used DDS from the IBM-supplied source le QDDSSRC, and the source le member name is ORDHDRL (the same as the le name specied on the CRTLF command). The le ORDHDRL with one member of the same name is placed in the library DSTPRODLB.

Creating a Logical File with More Than One Record Format

A multiple format logical le lets you use related records from two or more physical les by referring to only one logical le. Each record format is always associated with one or more physical les. You can use the same physical le in more than one record format.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER DETAIL FILE (ORDDTLP) - PHYSICAL FILE RECORD DEFINITION A REF(DSTREF) A R ORDDTL TEXT('Order detail record') A CUST R A ORDER R A LINE R A ITEM R A QTYORD R A DESCRP R A PRICE R A EXTENS R A WHSLOC R A ORDATE R A CUTYPE R A STATE R A ACTMTH R A ACTYR R A

Figure 11. DDS for a Physical File (ORDDTLP) Built from a Field Reference File

54

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER HEADER FILE (ORDHDRP) - PHYSICAL FILE RECORD DEFINITION A REF(DSTREFP) A R ORDHDR TEXT('Order header record') A CUST R A ORDER R A ORDATE R A CUSORD R A SHPVIA R A ORDSTS R A OPRNME R A ORDMNT R A CUTYPE R A INVNBR R A PRTDAT R A SEQNBR R A OPNSTS R A LINES R A ACTMTH R A ACTYR R A STATE R A

Figure 12. DDS for a Physical File (ORDHDRP) Built from a Field Reference File

The following example shows how to create a logical le ORDFILL with two record formats. One record format is dened for order header records from the physical le ORDHDRP; the other is dened for order detail records from the physical le ORDDTLP. ( Figure 11 on page 54 shows the DDS for the physical le ORDDTLP, Figure 12 shows the DDS for the physical le ORDHDRP, and Figure 13 shows the DDS for the logical le ORDFILL.) The logical le record format ORDHDR uses one key eld, Order, for sequencing; the logical le record format ORDDTL uses two keys elds, Order and Line, for sequencing.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* ORDER TRANSACTION LOGICAL FILE (ORDFILL) A R ORDHDR PFILE(ORDHDRP) A K ORDER A A R ORDDTL PFILE(ORDDTLP) A K ORDER A K LINE A

Figure 13. DDS for the Logical File ORDFILL

To create the logical le ORDFILL with two associated physical les, use a Create Logical File (CRTLF) command like the following:
CRTLF FILE(DSTPRODLB/ORDFILL) TEXT('Order transaction logical file')

The DDS source is in the member ORDFILL in the le QDDSSRC. The le ORDFILL with a member of the same name is placed in the DSTPRODLB library. The access path for the logical le member ORDFILL arranges records from both the ORDHDRP and ORDDTLP les. Record formats for both physical les are keyed on Order as the common eld. Because of the order in which they were specied in the logical le description, they are merged in Order sequence with duplicates between les retrieved rst from the header le ORDHDRP and second
Chapter 3. Setting Up Logical Files

55

from the detail le ORDDTLP. Because FIFO, LIFO, or FCFO are not specied, the order of retrieval of duplicate keys in the same le is not guaranteed. Note: In certain circumstances, it is better to use multiple logical les, rather than to use a multiple-format logical le. For example, when keyed access is used with a multiple-format logical le, it is possible to experience poor performance if one of the les has very few records. Even though there are multiple formats, the logical le has only one index, with entries from each physical le. Depending on the kind of processing being done by the application program (for example, using RPG SETLL and READE with a key to process the small le), the system might have to search all index entries in order to nd an entry from the small le. If the index has many entries, searching the index might take a long time, depending on the number of keys from each le and the sequence of keys in the index. (If the small le has no records, performance is not affected, because the system can take a fast path and avoid searching the index.)

Controlling How Records Are Retrieved in a File with Multiple Formats

In a logical le with more than one record format, key eld denitions are required. Each record format has its own key denition, and the record format key elds can be dened to merge the records of the different formats. Each record format does not have to contain every key eld in the key. Consider the following records: Header Record Format:
Record 1 2 Order 41882 32133 Cust 41394 28674 Ordate 050688 060288

Detail Record Format:

Record A B C D E Order 32133 32133 41882 32133 41882 Line 01 03 02 02 01 Item 46412 12481 46412 14201 08265 Qtyord 25 4 10 110 40 Extens 125000 001000 050000 454500 008000

In DDS, the header record format is dened before the detail record format. If the access path uses the Order eld as the rst key eld for both record formats and the Line eld as the second key eld for only the second record format, both in ascending sequence, the order of the records in the access path is: Record 2 Record A Record D Record B Record 1 Record E Record C

56

OS/400 DB2 for AS/400 Database Programming V4R3

Note: Records with duplicate key values are arranged rst in the sequence in which the physical les are specied. Then, if duplicates still exist within a record format, the duplicate records are arranged in the order specied by the FIFO, LIFO, or FCFO keyword. For example, if the logical le specied the DDS keyword FIFO, then duplicate records within the format would be presented in rst-in-rst-out sequence. For logical les with more than one record format, you can use the *NONE DDS function for key elds to separate records of one record format from records of other record formats in the same access path. Generally, records from all record formats are merged based on key values. However, if *NONE is specied in DDS for a key eld, only the records with key elds that appear in all record formats before the *NONE are merged. The logical le in the following example contains three record formats, each associated with a different physical le:
Record Format EMPMSTR EMPHIST EMPEDUC Physical File EMPMSTR EMPHIST EMPEDUC Key Fields Empnbr (employee number) 1 Empnbr, Empdat (employed date) 2 Empnbr, Clsnbr (class number) 3

Note: All record formats have one key eld in common, the Empnbr eld. The DDS for this example is:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A A K EMPNBR 1 A A K EMPNBR 2 A K EMPDAT A A K EMPNBR 3 A K *NONE A K CLSNBR A

*NONE is assumed for the second and third key elds for EMPMSTR and the third key eld for EMPHIST because no key elds follow these key eld positions. The following shows the arrangement of the records:
Empnbr 426 426 426 426 427 427 427 Empdat Clsnbr Record Format Name EMPMSTR EMPHIST EMPEDUC EMPEDUC EMPMSTR EMPHIST EMPEDUC

6/15/74 412 520 9/30/75 412

*NONE serves as a separator for the record formats EMPHIST and EMPEDUC. All the records for EMPHIST with the same Empnbr eld are grouped together and

Chapter 3. Setting Up Logical Files

57

sorted by the Empdat eld. All the records for EMPEDUC with the same Empnbr eld are grouped together and sorted by the Clsnbr eld. Note: Because additional key eld values are placed in the key sequence access path to guarantee the above sequencing, duplicate key values are not predictable. See the DDS Reference for additional examples of the *NONE DDS function.

Controlling How Records Are Added to a File with Multiple Formats

To add a record to a multiple format logical le, identify the member of the based-on physical le to which you want the record written. If the application you are using does not allow you to specify a particular member within a format, each of the formats in the logical le needs to be associated with a single physical le member. If one or more of the based-on physical les contains more than one member, you need to use the DTAMBRS parameter, described in Logical File Members, to associate a single member with each format. Finally, give each format in the multiple format logical le a unique name. If the multiple format logical le is dened in this way, then when you specify a format name on the add operation, you target a particular physical le member into which the record is added. When you add records to a multiple-format logical le and your application program uses a le name instead of a record format name, you need to write a format selector program. For more information about format selector programs, see Identifying Which Record Format to Add in a File with Multiple Formats on page 182 .

Logical File Members

You can dene members in logical les to separate the data into logical groups. The logical le member can be associated with one physical le member or with several physical le members. The following illustrates this concept:

58

OS/400 DB2 for AS/400 Database Programming V4R3

LF1 M1 M1

LF1 M2 M3

LF1 M1 M2

PF1

PF2

PF1

M1

M2

M3

M1

M2

M3

M1

M2

M3

LF1 M1 M2 M3

PF1

PF2

PF3

M1

M2

M1

M2

M3

M1

M2

M3
RSLH251-0

The record formats used with all logical members in a logical le must be dened in DDS when the le is created. If new record formats are needed, another logical le or record format must be created. The attributes of an access path are determined by information specied in DDS and on commands when the logical le is created. The selection of data members is specied in the DTAMBRS parameter on the Create Logical File (CRTLF) and Add Logical File Member (ADDLFM) commands. When a logical le is dened, the physical les used by the logical le are specied in DDS by the record level PFILE or JFILE keyword. If multiple record formats are dened in DDS, a PFILE keyword must be specied for each record format. You can specify one or more physical les for each PFILE keyword. When a logical le is created or a member is added to the le, you can use the DTAMBRS parameter on the Create Logical File (CRTLF) or the Add Logical File Member (ADDLFM) command to specify which members of the physical les used by the logical le are to be used for data. *NONE can be specied as the physical le member name if no members from a physical le are to be used for data. In the following example, the logical le has two record formats dened:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A 00010A R LOGRCD2 PFILE(PF1 PF2) A . A . A . 00020A R LOGRCD3 PFILE(PF1 PF2 PF3) A . A . A . A

Chapter 3. Setting Up Logical Files

59

If the DTAMBRS parameter is specied on the CRTLF or ADDLFM command as in the following example:
DTAMBRS((PF1 M1) (PF2 (M1 M2)) (PF1 M1) (PF2 (*NONE)) (PF3 M3))

Record format LOGRCD2 is associated with physical le member M1 in PF1 and M1 and M2 in le PF2. Record format LOGRCD3 is associated with M1 in PF1 and M3 in PF3. No members in PF2 are associated with LOGRCD3. If the same physical le name is specied on more than one PFILE keyword, each occurrence of the physical le name is handled as a different physical le. If a library name is not specied for the le on the PFILE keyword, the library list is used to nd the physical le when the logical le is created. The physical le name and the library name then become part of the logical le description. The physical le names and the library names specied on the DTAMBRS parameter must be the same as those stored in the logical le description. If a le name is not qualied by a library name on the DTAMBRS parameter, the library name defaults to *CURRENT, and the system uses the library name that is stored in the logical le description for the respective physical le name. This library name is either the library name that was specied for the le on the PFILE DDS keyword or the name of the library in which the le was found using the library list when the logical le was created. When you add a member to a logical le, you can specify data members as follows: v Specify no associated physical le members (DTAMBRS (*ALL) default). The logical le member is associated with all the physical le members of all physical les in all the PFILE keywords specied in the logical le DDS. v Specify the associated physical le members (DTAMBRS parameter). If you do not specify library names, the logical le determines the libraries used. When more than one physical le member is specied for a physical le, the member names should be specied in the order in which records are to be retrieved when duplicate key values occur across those members. If you do not want to include any members from a particular physical le, either do not specify the physical le name or specify the physical le name and *NONE for the member name. This method can be used to dene a logical le member that contains a subset of the record formats dened for the logical le. You can use the Create Logical File (CRTLF) command to create the rst member when you create the logical le. Subsequent members must be added using the Add Logical File Member (ADDLFM) command. However, if you are going to add more members, you must specify more than 1 for the MAXMBRS parameter on the CRTLF command. The following example of adding a member to a logical le uses the CRTLF command used earlier in Creating a Logical File on page 53.
CRTLF FILE(DSTPRODLB/ORDHDRL) MBR(*FILE) DTAMBRS(*ALL) TEXT('Order header logical file')

*FILE is the default for the MBR parameter and means the name of the member is the same as the name of the le. All the members of the associated physical le (ORDHDRP) are used in the logical le (ORDHDRL) member. The text description is the text description of the member.

60

OS/400 DB2 for AS/400 Database Programming V4R3

Join Logical File Considerations

This section covers the following topics: v Basic concepts of joining two physical les (Example 1) v Setting up a join logical le v Using more than one eld to join les (Example 2) v Handling duplicate records in secondary les using the JDUPSEQ keyword (Example 3) v Handling join elds whose attributes do not match (Example 4) v Using elds that never appear in the record format to join lesneither elds (Example 5) v Specifying key elds in join logical les (Example 6) v Specifying select/omit statements in join logical les v Joining three or more physical les (Example 7) v Joining a physical le to itself (Example 8) v Using default data for records missing from secondary lesthe JDFTVAL keyword (Example 9) v Describing a complex join logical le (Example 10) v Performance considerations v Data integrity considerations v Summary of rules for join logical les In general, the examples in this section include a picture of the les, DDS for the les, and sample data. For Example 1, several cases are given that show how to join les in different situations (when data in the physical les varies). In the examples, for convenience and ease of recognition, join logical les are shown with the label JLF, and physical les are illustrated with the labels PF1, PF2, PF3, and so forth.

Basic Concepts of Joining Two Physical Files (Example 1)

A join logical le is a logical le that combines (in one record format) elds from two or more physical les. In the record format, not all the elds need to exist in all the physical les. The following example illustrates a join logical le that joins two physical les. This example is used for the ve cases discussed in Example 1.

Chapter 3. Setting Up Logical Files

61

JLF Employee Number Name Salary PF1 PF2 Employee Number Employee Number Name Salary

In this example, employee number is common to both physical les (PF1 and PF2), but name is found only in PF1, and salary is found only in PF2. With a join logical le, the application program does one read operation (to the record format in the join logical le) and gets all the data needed from both physical les. Without the join specication, the logical le would contain two record formats, one based on PF1 and the other based on PF2, and the application program would have to do two read operations to get all the needed data from the two physical les. Thus, join provides more exibility in designing your database. However, a few restrictions are placed on join logical les: v You cannot change a physical le through a join logical le. To do update, delete, or write (add) operations, you must create a second multiple format logical le and use it to change the physical les. You can also use the physical les, directly, to do the change operations. v You cannot use DFU to display a join logical le. v You can specify only one record format in a join logical le. v The record format in a join logical le cannot be shared. v A join logical le cannot share the record format of another le. v Key elds must be elds dened in the join record format and must be elds from the rst le specied on the JFILE keyword (which is called the primary le). v Select/omit elds must be elds dened in the join record format, but can come from any of the physical les. v Commitment control cannot be used with join logical les. The following shows the DDS for Example 1:

62

OS/400 DB2 for AS/400 Database Programming V4R3

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JOINREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(NBR NBR) A NBR JREF(PF1) A NAME A SALARY A K NBR A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 A NBR 10 A NAME 20 A K NBR A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC2 A NBR 10 A SALARY 7 2 A K NBR A

Figure 14. DDS Example for Joining Two Physical Files

The following describes the DDS for the join logical le in Example 1 (see the DDS Reference for more information on the specic keywords): The record level specication identies the record format name used in the join logical le. R JFILE Identies the record format. Only one record format can be placed in a join logical le. Replaces the PFILE keyword used in simple and multiple-format logical les. You must specify at least two physical les. The rst le specied on the JFILE keyword is the primary le. The other les specied on the JFILE keyword are secondary les.

The join specication describes the way a pair of physical les is joined. The second le of the pair is always a secondary le, and there must be one join specication for each secondary le. J Identies the start of a join specication. You must specify at least one join specication in a join logical le. A join specication ends at the rst eld name specied in positions 19 through 28 or at the next J specied in position 17. Identies which two les are joined by the join specication. If only two physical les are joined by the join logical le, the JOIN keyword is optional. See Joining Three or More Physical Files (Example 7) on page 78 later in this section for an example of how to use this keyword. Identies the join elds that join records from the physical les specied on the JOIN. JFLD must be specied at least once for each join specication. The join elds are elds common to the physical les. The

JOIN

JFLD

Chapter 3. Setting Up Logical Files

63

rst join eld is a eld from the rst le specied on the JOIN keyword, and the second join eld is a eld from the second le specied on the JOIN keyword. Join elds, except character type elds, must have the same attributes (data type, length, and decimal positions). If the elds are character type elds, they do not need to have the same length. If you are joining physical le elds that do not have the same attributes, you can redene them for use in a join logical le. See Using Join Fields Whose Attributes Are Different (Example 4) on page 74 for a description and example. The eld level specication identies the elds included in the join logical le. Field names Species which elds (in this example, Nbr, Name, and Salary) are used by the application program. At least one eld name is required. You can specify any eld names from the physical les used by the logical le. You can also use keywords like RENAME, CONCAT, or SST as you would in simple and multiple format logical les. In the record format (which follows the join specication level and precedes the key eld level, if any), the eld names must uniquely identify which physical le the eld comes from. In this example, the Nbr eld occurs in both PF1 and PF2. Therefore, the JREF keyword is required to identify the le from which the Nbr eld description will be used.

JREF

The key eld level specication is optional, and includes the key eld names for the join logical le. K Identies a key eld specication. The K appears in position 17. Key eld specications are optional.

Key eld names Key eld names (in this example, Nbr is the only key eld) are optional and make the join logical le an indexed (keyed sequence) le. Without key elds, the join logical le is an arrival sequence le. In join logical les, key elds must be elds from the primary le, and the key eld name must be specied in positions 19 through 28 in the logical le record format. The select/omit eld level specication is optional, and includes select/omit eld names for the join logical le. S or O Identies a select or omit specication. The S or O appears in position 17. Select/omit specications are optional.

Select/omit eld names Only those records meeting the select/omit values will be returned to the program using the logical le. Select/omit elds must be specied in positions 19 through 28 in the logical le record format.

Reading a Join Logical File

The following cases describe how the join logical le in Figure 14 on page 63 presents records to an application program.

64

OS/400 DB2 for AS/400 Database Programming V4R3

The PF1 le is specied rst on the JFILE keyword, and is therefore the primary le. When the application program requests a record, the system does the following: 1. Uses the value of the rst join eld in the primary le (the Nbr eld in PF1). 2. Finds the rst record in the secondary le with a matching join eld (the Nbr eld in PF2 matches the Nbr eld in PF1). 3. For each match, joins the elds from the physical les into one record and provides this record to your program. Depending on how many records are in the physical les, one of the following conditions could occur: a. For all records in the primary le, only one matching record is found in the secondary le. The resulting join logical le contains a single record for each record in the primary le. See Matching Records in Primary and Secondary Files (Case 1). b. For some records in the primary le, no matching record is found in the secondary le. If you specify the JDFTVAL keyword: v For those records in the primary le that have a matching record in the secondary le, the system joins to the secondary, or multiple secondaries. The result is one or more records for each record in the primary le. v For those records in the primary le that do not have a matching record in the secondary le, the system adds the default value elds for the secondary le and continues the join operation. You can use the DFT keyword in the physical le to dene which defaults are used. See Record Missing in Secondary File; JDFTVAL Keyword Not Specied (Case 2A) on page 66 and Record Missing in Secondary File; JDFTVAL Keyword Specied (Case 2B) on page 66. Note: If the DFT keyword is specied in the secondary le, the value specied for the DFT keyword is used in the join. The result would be at least one join record for each primary record. v If a record exists in the secondary le, but the primary le has no matching value, no record is returned to your program. A second join logical le can be used that reverses the order of primary and secondary les to determine if secondary le records exist with no matching primary le records. If you do not specify the JDFTVAL keyword: v If a matching record in a secondary le exists, the system joins to the secondary, or multiple secondaries. The result is one or more records for each record in the primary le. v If a matching record in a secondary le does not exist, the system does not return a record. Note: When the JDFTVAL is not specied, the system returns a record only if a match is found in every secondary le for a record in the primary le. In the following examples, cases 1 through 4 describe sequential read operations, and case 5 describes reading by key.

Matching Records in Primary and Secondary Files (Case 1)

Assume that a join logical le is specied as in Figure 14 on page 63, and that four records are contained in both PF1 and PF2, as follows:

Chapter 3. Setting Up Logical Files

65

PF1 235 Anne 440 Doug 500 Mark 729 Sue

PF2 235 1700.00 440 950.50 500 2100.00 729 1400.90

The program does four read operations and gets the following records:
JLF 235 Anne 1700.00 440 Doug 950.50 500 Mark 2100.00 729 Sue 1400.90

Record Missing in Secondary File; JDFTVAL Keyword Not Specied (Case 2A)
Assume that a join logical le is specied as in Figure 14 on page 63, and that there are four records in PF1 and three records in PF2, as follows:
PF1 235 Anne 440 Doug 500 Mark 729 Sue PF2 235 1700.00 No record was 440 950.50 found for number 729 1400.90 500 in PF2

With the join logical le shown in Example 1, the program reads the join logical le and gets the following records:
JLF 235 Anne 1700.00 440 Doug 950.50 729 Sue 1400.90

If you do not specify the JDFTVAL keyword and no match is found for the join eld in the secondary le, the record is not included in the join logical le.

Record Missing in Secondary File; JDFTVAL Keyword Specied (Case 2B)

Assume that a join logical le is specied as in Figure 14 on page 63, except that the JDFTVAL keyword is specied, as shown in the following DDS:

66

OS/400 DB2 for AS/400 Database Programming V4R3

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A JDFTVAL A R JOINREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(NBR NBR) A NBR JREF(PF1) A NAME A SALARY A K NBR A

The program reads the join logical le and gets the following records:
JLF 235 Anne 1700.00 A record for number 500 440 Doug 950.50 is returned if JDFTVAL is 500 Mark 0000.00 specified (but the SALARY 729 Sue 1400.90 is 0).

With JDFTVAL specied, the system returns a record for 500, even though the record is missing in PF2. Without that record, some eld values can be missing in the join record (in this case, the Salary eld is missing). With JDFTVAL specied, missing character elds normally use blanks; missing numeric elds use zeros. However, if the DFT keyword is specied for the eld in the physical le, the default value specied on the DFT keyword is used.

Secondary File Has More Than One Match for a Record in the Primary File (Case 3)
Assume that a join logical le is specied as in Figure 14 on page 63, and that four records in PF1 and ve records in PF2, as follows:
PF1 235 Anne 440 Doug 500 Mark 729 Sue PF2 235 1700.00 Duplicate record 235 1500.00 was found in PF2 440 950.50 for number 235. 500 2100.00 729 1400.90

The program gets ve records:

Chapter 3. Setting Up Logical Files

67

JLF Order of records received 235 Anne 1700.00 for 235 is unpredictable 235 Anne 1500.00 unless you specify the 440 Doug 950.50 JDUPSEQ keyword. 500 Mark 2100.00 729 Sue 1400.90

For more information, see Reading Duplicate Records in Secondary Files (Example 3) on page 72.

Extra Record in Secondary File (Case 4)

Assume that a join logical le is specied as in Figure 14 on page 63, and that four records are contained in PF1 and ve records in PF2, as follows:
PF1 235 Anne 440 Doug 500 Mark 729 Sue PF2 235 1700.00 Record for 301 1500.00 number 301 is 440 950.50 only in PF2. 500 2100.00 729 1400.90

The program reads the join logical le and gets only four records, which would be the same even if JDFTVAL was specied (because a record must always be contained in the primary le to get a join record):
JLF 235 Anne 1700.00 440 Doug 950.50 500 Mark 2100.00 729 Sue 1400.90

Random Access (Case 5)

Assume that a join logical le is specied as in Figure 14 on page 63. Note that the join logical le has key elds dened. This case shows which records would be returned for a random access read operation using the join logical le. Assume that PF1 and PF2 have the following records:

68

OS/400 DB2 for AS/400 Database Programming V4R3

PF1 235 Anne 440 Doug 500 Mark 729 Sue 997 Tim

PF2 235 1700.00 440 950.50 729 1400.90 984 878.25 997 331.00 997 555.00

No record was found for number 500 in PF2. Record for number 984 is only in PF2. Duplicate records were found for number 997 in PF2.

The program can get the following records: Given a value of 235 from the program for the Nbr eld in the logical le, the system supplies the following record:
235 Anne 1700.00

Given a value of 500 from the program for the Nbr eld in the logical le and with the JDFTVAL keyword specied, the system supplies the following record:
500 Mark 0.00

Note: If the JDFTVAL keyword was not specied in the join logical le, no record would be found for a value of 500 because no matching record is contained in the secondary le. Given a value of 984 from the program for the Nbr eld in the logical le, the system supplies no record and a no record found exception occurs because record 984 is not in the primary le. Given a value of 997 from the program for the Nbr eld in the logical le, the system returns one of the following records:
997 Tim 331.00 or 997 Tim 555.00

Which record is returned to the program cannot be predicted. To specify which record is returned, specify the JDUPSEQ keyword in the join logical le. See Reading Duplicate Records in Secondary Files (Example 3) on page 72.

Chapter 3. Setting Up Logical Files

69

Notes: 1. With random access, the application programmer must be aware that duplicate records could be contained in PF2, and ensure that the program does more than one read operation for records with duplicate keys. If the program were using sequential access, a second read operation would get the second record. 2. If you specify the JDUPSEQ keyword, the system can create a separate access path for the join logical le (because there is less of a chance the system will nd an existing access path that it can share). If you omit the JDUPSEQ keyword, the system can share the access path of another le. (In this case, the system would share the access path of PF2.)

Setting Up a Join Logical File

To set up a join logical le, do the following: 1. Find the eld names of all the physical le elds you want in the logical le record format. (You can display the elds contained in les using the Display File Field Description [DSPFFD] command.) 2. Describe the elds in the record format. Write the eld names in a vertical list. This is the start of the record format for the join logical le. Note: You can specify the eld names in any order. If the same eld names appear in different physical les, specify the name of the physical le on the JREF keyword for those elds. You can rename elds using the RENAME keyword, and concatenate elds from the same physical le using the CONCAT keyword. A subset of an existing character, hexadecimal, or zoned decimal eld can be dened using the SST keyword. The substring of a character or zoned decimal eld is a character eld, and the substring of a hexadecimal eld is also a hexadecimal eld. You can redene elds: changing their data type, length, or decimal positions. 3. Specify the names of the physical les as parameter values on the JFILE keyword. The rst name you specify is the primary le. The others are all secondary les. For best performance, specify the secondary les with the least records rst after the primary le. 4. For each secondary le, code a join specication. On each join specication, identify which pair of les are joined (using the JOIN keyword; optional if only one secondary le), and identify which elds are used to join the pair (using the JFLD keyword; at least one required in each join specication). 5. Optionally, specify the following: a. The JDFTVAL keyword. Do this if you want to return a record for each record in the primary le even if no matching record exists in a secondary le. b. The JDUPSEQ keyword. Do this for elds that might have duplicate values in the secondary les. JDUPSEQ species on which eld (other than one of the join elds) to sort these duplicates, and the sequence that should be used. c. Key elds. Key elds cannot come from a secondary le. If you omit key elds, records are returned in arrival sequence as they appear in the primary le. d. Select/omit elds. In some situations, you must also specify the dynamic selection (DYNSLT) keyword at the le level. e. Neither elds. For a description, see Describing Fields That Never Appear in the Record Format (Example 5) on page 75.

70

OS/400 DB2 for AS/400 Database Programming V4R3

Using More Than One Field to Join Files (Example 2)

You can specify more than one join eld to join a pair of les. The following shows the elds in the logical le and the two physical les.

JLF Part Number Color Price Quantity on Hand PF1 PF2 Part Number Part Number Color Color Price Quantity on Hand Vendor Warehouse

The DDS for these les is as follows:

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JOINREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(PTNBR PTNBR) A JFLD(COLOR COLOR) A PTNBR JREF(PF1) A COLOR JREF(PF1) A PRICE A QUANTOH A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 A PTNBR 4 A COLOR 20 A PRICE 7 2 A VENDOR 40 A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC2 A PTNBR 4 A COLOR 20 A QUANTOH 5 0 A WAREHSE 30 A

Assume that the physical les have the following records:

Chapter 3. Setting Up Logical Files

71

PF1 PF2 100 Black 22.50 ABC Corp. 100 Black 23 ABC Corp. 100 White 20.00 Ajax Inc. 100 White 15 Ajax Inc. 120 Yellow 3.75 ABC Corp. 120 Yellow 120 ABC Corp. 187 Green 110.95 ABC Corp. 187 Green 0 ABC Corp. 187 Red 110.50 ABC Corp. 187 Red 2 ABC Corp. 190 Blue 40.00 Ajax Inc. 190 White 2 Ajax Inc. @

If the le is processed sequentially, the program receives the following records:

JLF 100 Black 22.50 23 100 White 20.00 15 120 Yellow 3.75 102 187 Green 110.95 0 187 Red 110.50 2

Note that no record for part number 190, color blue, is available to the program, because a match was not found on both elds in the secondary le. Because JDFTVAL was not specied, no record is returned.

Reading Duplicate Records in Secondary Files (Example 3)

Sometimes a join to a secondary le produces more than one record from the secondary le. When this occurs, specifying the JDUPSEQ keyword in the join specication for that secondary le tells the system to base the order of the duplicate records on the specied eld in the secondary le. The DDS for the physical les and for the join logical le are as follows:

72

OS/400 DB2 for AS/400 Database Programming V4R3

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(NAME1 NAME2) A JDUPSEQ(TELEPHONE) A NAME1 A ADDR A TELEPHONE A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 A NAME1 10 A ADDR 20 A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC2 A NAME2 10 A TELEPHONE 8 A

Figure 15. DDS Example Using the JDUPSEQ Keyword

The physical les have the following records:

PF1 PF2 Anne 120 1st St. Anne 555-1111 Doug 40 Pillsbury Anne 555-6666 Mark 2 Lakeside Dr. Anne 555-2222 Doug 555-5555

The join logical le returns the following records:

JLF Anne 120 1st St. 555-1111 Anne's telephone Anne 120 1st St. 555-2222 numbers are in Anne 120 1st St. 555-6666 ascebdubg order. Doug 40 Pillsbury 555-5555

The program reads all the records available for Anne, then Doug, then Mark. Anne has one address, but three telephone numbers. Therefore, there are three records returned for Anne. The records for Anne sort in ascending sequence by telephone number because the JDUPSEQ keyword sorts in ascending sequence unless you specify *DESCEND as the keyword parameter. The following example shows the use of *DESCEND in DDS:

Chapter 3. Setting Up Logical Files

73

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(NAME1 NAME2) A JDUPSEQ(TELEPHONE *DESCEND) A NAME1 A ADDR A TELEPHONE A

When you specify JDUPSEQ with *DESCEND, the records are returned as follows:
JLF Anne 120 1st St. 555-6666 Anne's telephone Anne 120 1st St. 555-2222 numbers are in Anne 120 1st St. 555-1111 descending order. Doug 40 Pillsbury 555-5555

Note: The JDUPSEQ keyword applies only to the join specication in which it is specied. For an example showing the JDUPSEQ keyword in a join logical le with more than one join specication, see A Complex Join Logical File (Example 10) on page 83.

Using Join Fields Whose Attributes Are Different (Example 4)

Fields from physical les that you are using as join elds generally have the same attributes (length, data type, and decimal positions). For example, as in Figure 15 on page 73, the Name1 eld is a character eld 10 characters long in physical le PF1, and can be joined to the Name2 eld, a character eld 10 characters long in physical le PF2. The Name1 and Name2 elds have the same characteristics and, therefore, can easily be used as join elds. You can also use character type elds that have different lengths as join elds without requiring any redenition of the elds. For example, if the NAME1 Field of PF1 was 10 characters long and the NAME2 eld of PF2 was 15 characters long, those elds could be used as join elds without redening one of the elds. The following is an example in which the join elds do not have the same attributes. The Nbr eld in physical le PF1 and the Nbr eld in physical le PF2 both have a length of 3 specied in position 34, but in the PF1 le the eld is zoned (S in position 35), and in the PF2 le the eld is packed (P in position 35). To join the two les using these elds as join elds, you must redene one or both elds to have the same attributes. The following illustrates the elds in the logical and physical les:

74

OS/400 DB2 for AS/400 Database Programming V4R3

JLF Employee Number Name Salary PF1 PF2 Employee Number (zoned) Employee Number (packed) Name Salary

The DDS for these les is as follows:

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JOINREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(NBR NBR) A NBR S JREF(2) A NAME A SALARY A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 A NBR 3S 0 <-Zoned A NAME 20 A K NBR A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC2 A NBR 3P 0 <-Packed A SALARY 7 2 A K NBR A

Note: In this example, the Nbr eld in the logical le comes from PF2, because JREF(2) is specied. Instead of specifying the physical le name, you can specify a relative le number on the JREF keyword; in this example, the 2 indicates PF2. Because the Nbr elds in the PF1 and PF2 les are used as the join elds, they must have the same attributes. In this example, they do not. Therefore, you must redene one or both of them to have the same attributes. In this example, to resolve the difference in the attributes of the two employee number elds, the Nbr eld in JLF (which is coming from the PF2 le) is redened as zoned (S in position 35 of JLF).

Describing Fields That Never Appear in the Record Format (Example 5)

A neither eld (N specied in position 38) can be used in join logical les for neither input nor output. Programs using the join logical le cannot see or read neither elds. Neither elds are not included in the record format. Neither elds cannot be key elds or used in select/omit statements in the joined le. You can
Chapter 3. Setting Up Logical Files

75

use a neither eld for a join eld (specied at the join specication level on the JFLD keyword) that is redened at the record level only to allow the join, but is not needed or wanted in the program. In the following example, the program reads the descriptions, prices, and quantity on hand of parts in stock. The part numbers themselves are not wanted except to bring together the records of the parts. However, because the part numbers have different attributes, at least one must be redened.
JLF Description Price Quantity on Hand PF1 PF2 Description Part Number Part Number Price Quantity on Hand

The DDS for these les is as follows:

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JOINREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(PRTNBR PRTNBR) A PRTNBR S N JREF(1) A DESC A PRICE A QUANT A K DESC A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 A DESC 30 A PRTNBR 6P 0 A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC2 A PRTNBR 6S 0 A PRICE 7 2 A QUANT 8 0 A

In PF1, the Prtnbr eld is a packed decimal eld; in PF2, the Prtnbr eld is a zoned decimal eld. In the join logical le, they are used as join elds, and the Prtnbr eld from PF1 is redened to be a zoned decimal eld by specifying an S in position 35 at the eld level. The JREF keyword identies which physical le the eld comes from. However, the eld is not included in the record format; therefore, N is specied in position 38 to make it a neither eld. A program using this le would not see the eld.

76

OS/400 DB2 for AS/400 Database Programming V4R3

In this example, a sales clerk can type a description of a part. The program can read the join logical le for a match or a close match, and display one or more parts for the user to examine, including the description, price, and quantity. This application assumes that part numbers are not necessary to complete a customer order or to order more parts for the warehouse.

Specifying Key Fields in Join Logical Files (Example 6)

If you specify key elds in a join logical le, the following rules apply: v The key elds must exist in the primary physical le. v The key elds must be named in the join record format in the logical le in positions 19 through 28. v The key elds cannot be elds dened as neither elds (N specied in position 38 for the eld) in the logical le. The following illustrates the rules for key elds:
JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JOINREC JFILE(PF1 PF2) A J JOIN(PF1 PF2) A JFLD(NBR NUMBER) A JFLD(FLD3 FLD31) A FLD1 RENAME(F1) A FLD2 JREF(2) A FLD3 35 N A NAME A TELEPHONE CONCAT(AREA LOCAL) A K FLD1 A K NAME A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 A NBR 4 A F1 20 A FLD2 7 2 A FLD3 40 A NAME 20 A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC2 A NUMBER 4 A FLD2 7 2 A FLD31 35 A AREA 3 A LOCAL 7 A

The following elds cannot be key elds: Nbr (not named in positions 19 through 28) Number (not named in positions 19 through 28) F1 (not named in positions 19 through 28) Fld31 (comes from a secondary le) Fld2 (comes from a secondary le) Fld3 (is a neither eld)
Chapter 3. Setting Up Logical Files

77

Area and Local (not named in positions 19 through 28) Telephone (is based on elds from a secondary le)

Specifying Select/Omit Statements in Join Logical Files

If you specify select/omit statements in a join logical le, the following rules apply: v The elds can come from any physical le the logical le uses (specied on the JFILE keyword). v The elds you specify on the select/omit statements cannot be elds dened as neither elds (N specied in position 38 for the eld). v In some circumstances, you must specify the DYNSLT keyword when you specify select/omit statements in join logical les. For more information and examples, see the DYNSLT keyword in the DDS Reference. For an example showing select/omit statements in a join logical le, see A Complex Join Logical File (Example 10) on page 83.

Joining Three or More Physical Files (Example 7)

You can use a join logical le to join as many as 32 physical les. These les must be specied on the JFILE keyword. The rst le specied on the JFILE keyword is the primary le; the other les are all secondary les. The physical les must be joined in pairs, with each pair described by a join specication. Each join specication must have one or more join elds identied. The following shows the elds in the les and one eld common to all the physical les in the logical le:
JLF2 Name Address Telephone Salary PF1 PF2 PF3 Name Name Name Address Telephone Salary

In this example, the Name eld is common to all the physical les (PF1, PF2, and PF3), and serves as the join eld. The following shows the DDS for the physical and logical les:

78

OS/400 DB2 for AS/400 Database Programming V4R3

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R JOINREC JFILE(PF1 PF2 P3) A J JOIN(PF1 PF2) A JFLD(NAME NAME) A J JOIN(PF2 PF3) A JFLD(NAME NAME) A NAME JREF(PF1) A ADDR A TELEPHONE A SALARY A K NAME A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC1 A NAME 10 A ADDR 20 A K NAME A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC2 A NAME 10 A TELEPHONE 7 A K NAME A PF3 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R REC3 A NAME 10 A SALARY 9 2 A K NAME A

Assume the physical les have the following records:

PF1 Anne 120 1st St. Doug 40 Pillsbury Mark 2 Lakeside Dr. Tom 335 Elm St. PF2 Anne 555-1111 Doug 555-5555 Mark 555-0000 Sue 555-3210 PF3 Anne 1700.00 Doug 950.00 Mark 2100.00

The program reads the following logical le records:

JLF Anne 120 1st St. 555-1111 1700.00 Doug 40 Pillsbury 555-5555 950.00 Mark 2 Lakeside Dr. 555-0000 2100.00

No record is returned for Tom because a record is not found for him in PF2 and PF3 and the JDFTVAL keyword is not specied. No record is returned for Sue because the primary le has no record for Sue.
Chapter 3. Setting Up Logical Files

79

Joining a Physical File to Itself (Example 8)

You can join a physical le to itself to read records that are formed by combining two or more records from the physical le itself. The following example shows how:
JLF Employee Number Name Manager's Name PF1 Employee Number Name Manager's Employee Number

The following shows the DDS for these les:

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A JDFTVAL A R JOINREC JFILE(PF1 PF1) A J JOIN(1 2) A JFLD(MGRNBR NBR) A NBR JREF(1) A NAME JREF(1) A MGRNAME RENAME(NAME) A JREF(2) A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RCD1 A NBR 3 A NAME 10 DFT('none') A MGRNBR 3 A

Notes: 1. Relative le numbers must be specied on the JOIN keyword because the same le name is specied twice on the JFILE keyword. Relative le number 1 refers to the rst physical le specied on the JFILE keyword, 2 refers to the second, and so forth. 2. With the same physical les specied on the JFILE keyword, the JREF keyword is required for each eld specied at the eld level. Assume the following records are contained in PF1:

80

OS/400 DB2 for AS/400 Database Programming V4R3

PF1 235 Anne 440 440 Doug 729 500 Mark 440 729 Sue 888

The program reads the following logical le records:

PF1 235 Anne Doug 440 Doug Sue 500 Mark Doug 729 Sue none

Note that a record is returned for the manager name of Sue because the JDFTVAL keyword was specied. Also note that the value none is returned because the DFT keyword was used on the Name eld in the PF1 physical le.

Using Default Data for Missing Records from Secondary Files (Example 9)
If you are joining more than two les, and you specify the JDFTVAL keyword, the default value supplied by the system for a join eld missing from a secondary le is used to join to other secondary les. If the DFT keyword is specied in the secondary le, the value specied for the DFT keyword is used in the logical le. The DDS for the les is as follows:

Chapter 3. Setting Up Logical Files

81

JLF |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A JDFTVAL A R JRCD JFILE(PF1 PF2 PF3) A J JOIN(PF1 PF2) A JFLD(NAME NAME) A J JOIN(PF2 PF3) A JFLD(TELEPHONE TELEPHONE) A NAME JREF(PF1) A ADDR A TELEPHONE JREF(PF2) A LOC A PF1 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RCD1 A NAME 20 A ADDR 40 A COUNTRY 40 A PF2 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RCD2 A NAME 20 A TELEPHONE 8 DFT('999-9999') A PF3 |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RCD3 A TELEPHONE 8 A LOC 30 DFT('No location assigned') A

Assume that PF1, PF2, and PF3 have the following records:
PF1 235 Anne 440 440 Doug 729 500 Mark 440 729 Sue 888

With JDFTVAL specied in the join logical le, the program reads the following logical le records:
PF1 235 Anne Doug 440 Doug Sue 500 Mark Doug 729 Sue none

In this example, complete data is found for Anne and Doug. However, part of the data is missing for Mark and Sue.

82

OS/400 DB2 for AS/400 Database Programming V4R3

v PF2 is missing a record for Mark because he has no telephone number. The default value for the Telephone eld in PF2 is dened as 999-9999 using the DFT keyword. In this example, therefore, 999-9999 is the telephone number returned when no telephone number is assigned. The JDFTVAL keyword specied in the join logical le causes the default value for the Telephone eld (which is 999-9999) in PF2 to be used to match with a record in PF3. (In PF3, a record is included to show a description for telephone number 999-9999.) Without the JDFTVAL keyword, no record would be returned for Mark. v Sues telephone number is not yet assigned a location; therefore, a record for 555-1144 is missing in PF3. Without JDFTVAL specied, no record would be returned for Sue. With JDFTVAL specied, the system supplies the default value specied on the DFT keyword in PF3 the Loc eld (which is No location assigned).

A Complex Join Logical File (Example 10)

The following example shows a more complex join logical le. Assume the data is in the following three physical les:
Vendor Master File (PF1) |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RCD1 TEXT('VENDOR INFORMATION') A VDRNBR 5 TEXT('VENDOR NUMBER') A VDRNAM 25 TEXT('VENDOR NAME') A STREET 15 TEXT('STREET ADDRESS') A CITY 15 TEXT('CITY') A STATE 2 TEXT('STATE') A ZIPCODE 5 TEXT('ZIP CODE') A DFT('00000') A PAY 1 TEXT('PAY TERMS') A Order File (PF2) |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RCD2 TEXT('VENDORS ORDER') A VDRNUM 5S 0 TEXT('VENDOR NUMBER') A JOBNBR 6 TEXT('JOB NUMBER') A PRTNBR 5S 0 TEXT('PART NUMBER') A DFT(99999) A QORDER 3S 0 TEXT('QUANTITY ORDERED') A UNTPRC 6S 2 TEXT('PRICE') A Part File (PF3) |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R RCD3 TEXT('DESCRIPTION OF PARTS') A PRTNBR 5S 0 TEXT('PART NUMBER') A DFT(99999) A DESCR 25 TEXT('DESCRIPTION') A UNITPRICE 6S 2 TEXT('UNIT PRICE') A WHSNBR 3 TEXT('WAREHOUSE NUMBER') A PRTLOC 4 TEXT('LOCATION OF PART') A QOHAND 5 TEXT('QUANTITY ON HAND') A

The join logical le record format should contain the following elds: Vdrnam (vendor name) Street, City, State, and Zipcode (vendor address) Jobnbr (job number) Prtnbr (part number)
Chapter 3. Setting Up Logical Files

83

Descr (description of part) Qorder (quantity ordered) Untprc (unit price) Whsnbr (warehouse number) Prtloc (location of part) The DDS for this join logical le is as follows:
Join Logical File (JLF) |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A 1 DYNSLT A 2 JDFTVAL A R RECORD1 JFILE(PF1 PF2 PF3) A 3 J JOIN(1 2) A JFLD(VDRNBR VDRNUM) A 4 JDUPSEQ(JOBNBR) A 5 J JOIN(2 3) A 6 JFLD(PRTNBR PRTNBR) A JFLD(UNTPRC UNITPRICE) A 7 VDRNUM 5A N TEXT('CHANGED ZONED TO CHAR') A VDRNAM A ADDRESS 8 CONCAT(STREET CITY STATE + A ZIPCODE) A JOBNBR A PRTNBR 9 JREF(2) A DESCR A QORDER A UNTPRC A WHSNBR A PRTLOC A 10 S VDRNAM COMP(EQ 'SEWING COMPANY') A S QORDER COMP(GT 5) A

1 2 3 4 5 6 7

The DYNSLT keyword is required because the JDFTVAL keyword and select elds are specied. The JDFTVAL keyword is specied to pick up default values in physical les. First join specication. The JDUPSEQ keyword is specied because duplicate vendor numbers occur in PF2. Second join specication. Two JFLD keywords are specied to ensure the correct records are joined from the PF2 and PF3 les. The Vdrnum eld is redened from zoned decimal to character (because it is used as a join eld and it does not have the same attributes in PF1 and PF2). The CONCAT keyword concatenates four elds from the same physical le into one eld. The JREF keyword must be specied because the Prtnbr eld exists in two physical les and you want to use the one in PF2. The select/omit elds are Vdrnam and Qorder. (Note that they come from two different physical les.)

8 9 10

84

OS/400 DB2 for AS/400 Database Programming V4R3

Performance Considerations
You can do the following to improve the performance of join logical les: v If the physical les you are joining have a different number of records, specify the physical le with fewest records rst (rst parameter following the JOIN keyword). v Consider using the DYNSLT keyword. See Dynamic Select/Omit on page 50 for more details. v Consider describing your join logical le so it can automatically share an existing access path. See Using Existing Access Paths on page 51 for more details. Note: Join logical les always have access paths using the second eld of the pair of elds specied in the JFLD keyword. This eld acts like a key eld in simple logical les. If an access path does not already exist, the access path is implicitly created with immediate maintenance.

Data Integrity Considerations

Unless you have a lock on the physical les used by the join logical le, the following can occur: v Your program reads a record for which there are two or more records in a secondary le. The system supplies one record to your program. v Another program updates the record in the primary le that your program has just read, changing the join eld. v Your program issues another read request. The system supplies the next record based on the current (new) value of the join eld in the primary le. These same considerations apply to secondary les as well.

Summary of Rules for Join Logical Files

Requirements
The principal requirements for join logical les are: v Each join logical le must have: Only one record format, with the JFILE keyword specied for it. At least two physical le names specied on the JFILE keyword. (The physical le names on the JFILE keyword do not have to be different les.) At least one join specication (J in position 17 with the JFLD keyword specied). A maximum of 31 secondary les. At least one eld name with eld use other than N (neither) at the eld level. v If only two physical les are specied for the JFILE keyword, the JOIN keyword is not required. Only one join specication can be included, and it joins the two physical les. v If more than two physical les are specied for the JFILE keyword, the following rules apply: The primary le must be the rst le of the pair of les specied on the rst JOIN keyword (the primary le can also be the rst of the pair of les specied on other JOIN keywords).
Chapter 3. Setting Up Logical Files

85

Note: Relative le numbers must be specied on the JOIN keyword and any JREF keyword when the same le name is specied twice on the JFILE keyword. Every secondary le must be specied only once as the second le of the pair of les on the JOIN keyword. This means that for every secondary le on the JFILE keyword, one join specication must be included (two secondary les would mean two join specications, three secondary les would mean three join specications). The order in which secondary les appear in join specications must match the order in which they are specied on the JFILE keyword.

Join Fields
The rules to remember about join elds are: v Every physical le you are joining must be joined to another physical le by at least one join eld. A join eld is a eld specied as a parameter value on the JFLD keyword in a join specication. v Join elds (specied on the JFLD keyword) must have identical attributes (length, data type, and decimal positions) or be redened in the record format of the join logical le to have the same attributes. If the join elds are of character type, the eld lengths may be different. v Join elds need not be specied in the record format of the join logical le (unless you must redene one or both so that their attributes are identical). v If you redene a join eld, you can specify N in position 38 (making it a neither eld) to prevent a program using the join logical le from using the redened eld. v The maximum length of elds used in joining physical les is equal to the maximum size of keys for physical and logical les (see Appendix A. Database File Sizes).

Fields in Join Logical Files

The rules to remember about elds in join logical les are: v Fields in a record format for a join logical le must exist in one of the physical les used by the logical le or, if CONCAT, RENAME, TRNTBL, or SST is specied for the eld, be a result of elds in one of the physical les. v Fields specied as parameter values on the CONCAT keyword must be from the same physical le. If the rst eld name specied on the CONCAT keyword is not unique among the physical les, you must specify the JREF keyword for that eld to identify which le contains the eld descriptions you want to use. v If a eld name in the record format for a join logical le is specied in more than one of the physical les, you must uniquely specify on the JREF keyword which le the eld comes from. v Key elds, if specied, must come from the primary le. Key elds in the join logical le need not be key elds in the primary le. v Select/omit elds can come from any physical le used by the join logical le, but in some circumstances the DYNSLT keyword is required. v If specied, key elds and select/omit elds must be dened in the record format. v Relative le numbers must be used for the JOIN and JREF keywords if the name of the physical le is specied more than once on the JFILE keyword.

86

OS/400 DB2 for AS/400 Database Programming V4R3

Miscellaneous
Other rules to keep in mind when using join logical les are: v Join logical les are read-only les. v Join record formats cannot be shared, and cannot share other record formats. v The following are not allowed in a join logical le: The REFACCPTH and FORMAT keywords Both elds (B specied in position 38)

Chapter 3. Setting Up Logical Files

87

88

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 4. Database Security

This chapter describes some of the database le security functions. The topics covered include database le security, public authority considerations, restricting the ability to change or delete any data in a le, restricting the ability to change any data in a particular column, and using logical les to secure data. For more information about using the security function on the AS/400 system, see the Security - Reference.

File and Data Authority

The following describes the types of authority that can be granted to a user for a database le.

Object Operational Authority

Object operational authority is required to: v Open the le for processing. (You must also have at least one data authority.) v Compile a program which uses the le description. v Display descriptive information about active members of a le. v Open the le for query processing. For example, the Open Query File (OPNQRYF) command opens a le for query processing. Note: You must also have the appropriate data authorities required by the options specied on the open operation.

Object Existence Authority

Object existence authority is required to: v Delete the le. v Save, restore, and free the storage of the le. If the object existence authority has not been explicitly granted to the user, the *SAVSYS special user authority allows the user to save, restore, and free the storage of a le. *SAVSYS is not the same as object existence authority. v Remove members from the le. v Transfer ownership of the le. Note: All these functions except save/restore also require object operational authority to the le.

Object Management Authority

Object management authority is required to: v Create a logical le with a keyed sequence access path (object management authority is required for the physical le referred to by the logical le). v Grant and revoke authority. You can grant and revoke only the authority that you already have. (You must also have object operational authority to the le.) v Change the le.

Copyright IBM Corp. 1997, 1998

89

v Add members to the le. (The owner of the le becomes the owner of the new member.) v Change the member in the le. v Move the le. v Rename the le. v Rename a member of the le. v Clear a member of the le. (Delete data authority is also required.) v Initialize a member of the le. (Add data authority is also required to initialize with default records; delete data authority is required to initialize with deleted records.) v Reorganize a member of the le. (All data authorities are also required.)

Object Alter Authority

Object alter authority is used for: v Many of the same operations as object management authority (see preceding section). Object alter authority is a replacement authority for object management authority.

Object Reference Authority

Object reference authority provides: v The authority needed to reference an object from another object such that operations on that object may be restricted by the referencing object. Adding a physical le referential constraint checks for either object management authority or object reference authority to the parent le. Physical le constraints are described in Chapter 15. Physical File Constraints and Chapter 16. Referential Integrity.

Data Authorities
Data authorities can be granted to physical and logical les.

Read Authority
You can read the records in the le.

Add Authority
You can add new records to the le.

Update Authority
You can update existing records. (To read a record for update, you must also have read authority.)

Delete Authority
You can delete existing records. (To read a record for deletion, you must also have read authority.)

90

OS/400 DB2 for AS/400 Database Programming V4R3

Execute Authority
Used mainly for libraries and programs. For example, if you are changing le associated with a trigger, you must have execute authority to the trigger program. If you do not have execute authority, the system will not invoke the trigger program. For detailed information on triggers, see Chapter 17. Triggers. Normally, the authority you have to the data in the le is not veried until you actually perform the input/output operation. However, the Open Query File (OPNQRYF) and Open Database File (OPNDBF) commands also verify data authority when the le is opened. If object operational authority is not granted to a user for a le, that user cannot open the le. The following example shows the relationship between authority granted for logical les and the physical les used by the logical le. The logical les LF1, LF2, and LF3 are based on the physical le PF1. USERA has read (*READ) and add (*ADD) authority to the data in PF1 and object operational (*OBJOPR), read (*READ), and add (*ADD) authority for LF1 and LF2. This means that USERA cannot open PF1 or use its data directly in any way because the user does not have object operational authority (*OBJOPR) to PF1; USERA can open LF1 and LF2 and read records from and add records to PF1 through LF1 and LF2. Note that the user was not given authority for LF3 and, therefore, cannot use it.
GRTOBJAUT OBJ(LF1) USER(USERA) AUT(*OBJOPR *READ *ADD)... GRTOBJAUT OBJ(LF2) USER(USERA) AUT(*OBJOPR *READ *ADD)... LF1 LF1 LF1 PFILE(PF1) PFILE(PF1) PFILE(PF1) (PF1) GRTOBJAUT OBJ(PF1) USER(USERA) AUT(*READ *ADD)...

Public Authority
When you create a le, you can specify public authority through the AUT parameter on the create command. Public authority is authority available to any user who does not have specic authority to the le or who is not a member of a group that has specic authority to the le. Public authority is the last authority check made. That is, if the user has specic authority to a le or the user is a member of a group with specic authority, then the public authority is not checked. Public authority can be specied as: v *LIBCRTAUT. The library in which the le is created is checked to determine the public authority of the le when the le is created. An authority is associated with each library. This authority is specied when the library is created, and all les created into the library are given this public authority if the *LIBCRTAUT value is specied for the AUT parameter of the Create File (CRTLF, CRTPF, and CRTSRCPF) commands. The *LIBCRTAUT value is the default public authority.
Chapter 4. Database Security

91

v *CHANGE. All users that do not have specic user or group authority to the le have authority to change data in the le. v *USE. All users that do not have specic user or group authority to the le have authority to read data in the le. v *EXCLUDE. Only the owner, security officer, users with specic authority, or users who are members of a group with specic authority can use the le. v *ALL. All users that do not have specic user or group authority to the le have all data authorities along with object operational, object management, and object existence authorities. v Authorization list name. An authorization list is a list of users and their authorities. The list allows users and their different authorities to be grouped together. Note: When creating a logical le, no data authorities are granted. Consequently, *CHANGE is the same as *USE, and *ALL does not grant any data authority. You can use the Edit Object Authority (EDTOBJAUT), Grant Object Authority (GRTOBJAUT), or Revoke Object Authority (RVKOBJAUT) commands to grant or revoke the public authority of a le.

Database File Capabilities

File capabilities are used to control which input/output operations are allowed for a database le independent of database le authority. When you create a physical le, you can specify if the le is update-capable and delete-capable by using the ALWUPD and ALWDLT parameters on the Create Physical File (CRTPF) and Create Source Physical File (CRTSRCPF) commands. By creating a le that is not update-capable and not delete-capable, you can effectively enforce an environment where data cannot be changed or deleted from a le once the data is written. File capabilities cannot be explicitly set for logical les. The le capabilities of a logical le are determined by the le capabilities of the physical les it is based on. You cannot change le capabilities after the le is created. You must delete the le then recreate it with the desired capability. The Display File Description (DSPFD) command can be used to determine the capabilities of a le.

Limiting Access to Specic Fields of a Database File

You can restrict user update and read requests to specic elds of a physical database le. There are two ways to do this: v Create a logical view of the physical le that includes only those elds to which you want your users to have access. See Using Logical Files to Secure Data on page 93 for more information. v Use the SQL GRANT statement to grant update authority to specic columns of an SQL table. See the DB2 for AS/400 SQL Programming book for more information.

92

OS/400 DB2 for AS/400 Database Programming V4R3

Using Logical Files to Secure Data

You can use a logical le to prevent a eld in a physical le from being viewed. This is accomplished by describing a logical le record format that does not include elds you do not want the user to see. For more information about this subject, see Describing Logical File Record Formats on page 39. You can also use a logical le to prevent one or more elds from being changed in a physical le by specifying, for those elds you want to protect, an I (input only) in position 38 of the DDS form. For more information about this subject, see Describing Field Use for Logical Files on page 41. You can use a logical le to secure records in a physical le based on the contents of one or more elds in that record. To secure records based on the contents of a eld, use the select and omit keywords when describing the logical le. For more information about this subject, see Selecting and Omitting Records Using Logical Files on page 46.

Chapter 4. Database Security

93

94

OS/400 DB2 for AS/400 Database Programming V4R3

Part 2. Processing Database Files in Programs

The chapters in this part include information on processing database les in your programs. This includes information on planning how the le will be used in the program or job and improving the performance of your program. Descriptions of the le processing parameters and run-time options that you can specify for more efficient le processing are included in this section. Another topic covered in this part is sharing database les across jobs so that they can be accessed by many users at the same time. Locks on les, records, or members that can prevent them from being shared across jobs are also discussed. Using the Open Query File (OPNQRYF) command and the Open Database File (OPNDBF) command to open database le members in a program is discussed. Examples, performance considerations, and guidelines to follow when writing a high-level language program are also included. Also, typical errors that can occur are discussed. Finally, basic database le operations are discussed. This discussion includes setting a position in the database le, and reading, updating, adding, and deleting records in a database le. A description of several ways to read database records is also included. Information on updating discusses how to change an existing database record in a logical or physical le. Information on adding a new record to a physical database member using the write operation is included. This section also includes ways you can close a database le when your program completes processing a database le member, disconnecting your program from the le. Messages to monitor when handling database le errors in a program are also discussed.

Copyright IBM Corp. 1997, 1998

95

96

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 5. Run Time Considerations

Before a le is opened for processing, you should consider how you will use the le in the program and job. A better understanding of the run-time le processing parameters can help you avoid unexpected results. In addition, you might improve the performance of your program. When a le is opened, the attributes in the database le description are merged with the parameters in the program. Normally, most of the information the system needs for your program to open and process the le is found in the le attributes and in the application program itself. Sometimes, however, it is necessary to override the processing parameters found in the le and in the program. For example, if you want to process a member of the le other than the rst member, you need a way to tell the system to use the member you want to process. The Override with Database File (OVRDBF) command allows you to do this. The OVRDBF command also allows you to specify processing parameters that can improve the performance of your job, but that cannot be specied in the le attributes or in the program. The OVRDBF command parameters take precedence over the le and program attributes. For more information on how overrides behave in the Integrated Language Environment see ILE Concepts book. This chapter describes the le processing parameters. The parameter values are determined by the high-level language program, the le attributes, and any open or override commands processed before the high-level language program is called. A summary of these parameters and where you specify them can be found in Run Time Summary on page 114. For more information about processing parameters from commands, see the CL Reference (Abridged) book for the following commands: v Create Physical File (CRTPF) v v v v Create Logical File (CRTLF) Create Source Physical File (CRTSRCPF) Add Physical File Member (ADDPFM) Add Logical File Member (ADDLFM)

v Change Physical File (CHGPF) v Change Physical File Member (CHGPFM) v Change Logical File (CHGLF) v Change Logical File Member (CHGLFM) v Change Source Physical File (CHGSRCPF) v Override with Database File (OVRDBF) v Open Database File (OPNDBF) v Open Query File (OPNQRYF) v Close File (CLOF)

Copyright IBM Corp. 1997, 1998

97

File and Member Name

FILE and MBR Parameter. Before you can process data in a database le, you must identify which le and member you want to use. Normally, you specify the le name and, optionally, the member name in your high-level language program. The system then uses this name when your program requests the le to be opened. To override the le name specied in your program and open a different le, you can use the TOFILE parameter on the Override with Database File (OVRDBF) command. If no member name is specied in your program, the rst member of the le (as dened by the creation date and time) is processed. If the member name cannot be specied in the high-level language program (some high-level languages do not allow a member name), or you want a member other than the rst member, you can use an Override with Database File (OVRDBF) command or an open command (OPNDBF or OPNQRYF) to specify the le and member you want to process (using the FILE and MBR parameters). To process all the members of a le, use the OVRDBF command with the MBR(*ALL) parameter specied. For example, if FILEX has three members and you want to process all the members, you can specify:
OVRDBF FILE(FILEX) MBR(*ALL)

If you specify MBR(*ALL) on the OVRDBF command, your program reads the members in the order they were created. For each member, your program reads the records in keyed or arrival sequence, depending on whether the le is an arrival sequence or keyed sequence le.

File Processing Options

The following section describes several run-time processing options, including identifying the le operations used by the program, specifying the starting le position, reusing deleted records, ignoring the keyed sequence access path, specifying how to handle end-of-le processing, and identifying the length of the record in the le.

Specifying the Type of Processing

OPTION Parameter. When you use a le in a program, the system needs to know what types of operations you plan to use for that le. For example, the system needs to know if you plan to just read data in the le or if you plan to read and update the data. The valid operation options are: input, output, update, and delete. The system determines the options you are using from information you specify in your high-level language program or from the OPTION parameter on the Open Database File (OPNDBF) and Open Query File (OPNQRYF) commands. The system uses the options to determine which operations are allowed in your program. For example, if you open a le for input only and your program tries an output operation, your program receives an error. Normally, the system veries that you have the required data authority when you do an input/output operation in your program. However, when you use the Open Query File (OPNQRYF) or Open Database File (OPNDBF) commands, the system veries at the time the le is opened that you have the required data authority to

98

OS/400 DB2 for AS/400 Database Programming V4R3

perform the operations specied on the OPTION parameter. For more information about data authority, see Data Authorities on page 90. The system also uses these options to determine the locks to use to protect the data integrity of the les and records being processed by your program. For more information on locks, see Sharing Database Files Across Jobs on page 102.

Specifying the Initial File Position

POSITION Parameter. The system needs to know where it should start processing the le after it is opened. The default is to start just before the rst record in the le (the rst sequential read operation will read the rst record). But, you can tell the system to start at the end of the le, or at a certain record in the middle of the le using the Override with Database File (OVRDBF) command. You can also dynamically set a position for the le in your program. For more information on setting position for a le in a program, see Setting a Position in the File on page 173 .

Reusing Deleted Records

REUSEDLT Parameter. When you specify REUSEDLT(*YES) on the Create Physical File (CRTPF) or Change Physical File (CHGPF) command, the following operations may work differently: v Arrival order becomes meaningless for a le that reuses deleted record space. Records might not be added at the end of the le. v End-of-le delay does not work for les that reuse deleted record space. v Applications that use DDM from a previous release system to a current release system may get different results when accessing les where deleted record space is reused. v One hundred percent reuse of deleted record space is not guaranteed. A le full condition may be reached or the le may be extended even though deleted record space still exists in the le. Because of the way the system reuses deleted record space, consider the following points before creating or changing a le to reuse deleted record space: v Files processed using relative record numbers and les used by an application to determine a relative record number that is used as a key into another le should not reuse deleted record space. v Files used as queues should not reuse deleted record space. v Any les used by applications that assume new record inserts are at the end of the le should not reuse deleted record space. If you decide to change an existing physical le to reuse deleted record space, and there are logical les with access paths with LIFO or FIFO duplicate key ordering over the physical le, you can re-create the logical les without the FIFO or LIFO attribute and avoid rebuilding the existing access path by doing the following: 1. Rename the existing logical le that has the FIFO or LIFO attribute. 2. Create a second logical le identical to the renamed le except that duplicate key ordering should not be specied for the le. Give the new le the original le name. The new le shares the access path of the renamed le. 3. Delete the renamed le.

Chapter 5. Run Time Considerations

99

Ignoring the Keyed Sequence Access Path

ACCPTH Parameter. When you process a le with a keyed sequence access path, you normally want to use that access path to retrieve the data. The system automatically uses the keyed sequence access path if a key eld is dened for the le. However, sometimes you can achieve better performance by ignoring the keyed sequence access path and processing the le in arrival sequence. You can tell the system to ignore the keyed sequence access path in some high-level languages, or on the Open Database File (OPNDBF) command. When you ignore the keyed sequence access path, operations that read data by key are not allowed. Operations are done sequentially along the arrival sequence access path. (If this option is specied for a logical le with select/omit values dened, the arrival sequence access path is used and only those records meeting the select/omit values are returned to the program. The processing is done as if the DYNSLT keyword was specied for the le.) Note: You cannot ignore the keyed sequence access path for logical le members that are based on more than one physical le member.

Delaying End of File Processing

EOFDLY Parameter. When you are reading a database le and your program reaches the end of the data, the system normally signals your program that there is no more data to read. Occasionally, instead of telling the program there is no more data, you might want the system to hold your program until more data arrives in the le. When more data arrives in the le, the program can read the newly arrived records. If you need that type of processing, you can use the EOFDLY parameter on the Override with Database File (OVRDBF) command. For more information on this parameter, see Waiting for More Records When End of File Is Reached on page 177. Note: End of le delay should not be used for les that reuse deleted records.

Specifying the Record Length

The system needs to know the length of the record your program will be processing, but you do not have to specify record length in your program. The system automatically determines this information from the attributes and description of the le named in your program. However, as an option, you can specify the length of the record in your high-level language program. If the le that is opened contains records that are longer than the length specied in the program, the system allocates a storage area to match the le members record length and this option is ignored. In this case, the entire record is passed to the program. (However, some high-level languages allow you to access only that portion of the record dened by the record length specied in the program.) If the le that is opened contains records that are less than the length specied in the program, the system allocates a storage area for the program-specied record length. The program can use the extra storage space, but only the record lengths dened for the le member are used for input/output operations.

100

OS/400 DB2 for AS/400 Database Programming V4R3

Ignoring Record Formats

When you use a multiple format logical le, the system assumes you want to use all formats dened for that le. However, if you do not want to use all of the formats, you can specify which formats you want to use and which ones you want to ignore. If you do not use this option to ignore formats, your program can process all formats dened in the le. For more information about this processing option, see your high-level language guide.

Determining If Duplicate Keys Exist

DUPKEYCHK Parameter. The set of keyed sequence access paths used to determine if the key is a duplicate key differs depending on the I/O operation that is performed. For input operations (reads), the keyed sequence access path used is the one that the le is opened with. Any other keyed sequence access paths that can exist over the physical le are not considered. Also, any records in the keyed sequence access path omitted because of select/omit specications are not considered when deciding if the key operation is a duplicate. For output (write) and update operations, all nonunique keyed sequence access paths of *IMMED maintenance that exist over the physical le are searched to determine if the key for this output or update operation is a duplicate. Only keyed sequence access paths that have *RBLD and *DLY maintenance are considered if the access paths are actively open over the le at feedback time. When you process a keyed le with a COBOL program, you can specify duplicate key feedback to be returned to your program through the COBOL language, or on the Open Database File (OPNDBF) or Open Query File (OPNQRYF) commands. However, in COBOL having duplicate key feedback returned can cause a decline in performance.

Data Recovery and Integrity

The following section describes data integrity run-time considerations.

Protecting Your File with the Journaling and Commitment Control

COMMIT Parameter. Journaling and commitment control are the preferred methods for data and transaction recovery on the AS/400 system. Database le journaling is started by running the Start Journal Physical File (STRJRNPF) command for the le. Access path journaling is started by running the Start Journal Access Path (STRJRNAP) command for the le or by using System-Managed Access-Path Protection (SMAPP). You tell the system that you want your les to run under commitment control through the Start Commitment Control (STRCMTCTL) command and through high-level language specications. You can also specify the commitment control (COMMIT) parameter on the Open Database File (OPNDBF) and Open Query File (OPNQRYF) commands. For more information on journaling and commitment control, see Chapter 13. Database Recovery Considerations, and the Backup and Recovery book.

Chapter 5. Run Time Considerations

101

If you are performing inserts, updates, or deletes on a le that is associated with a referential constraint and the delete rule, update rule, or both is other than RESTRICT, you must use journaling. For more information on journaling and referential constraints, see Chapter 16. Referential Integrity.

Writing Data and Access Paths to Auxiliary Storage

FRCRATIO and FRCACCPTH Parameters. Normally, the AS/400 integrated database management system determines when to write changed data from main storage to auxiliary storage. If you want to control when database changes are written to auxiliary storage, you can use the force write ratio (FRCRATIO) parameter on either the create, change, or override database le commands, and the force access path (FRCACCPTH) parameter on the create and change database le commands. Using the FRCRATIO and FRCACCPTH parameters have performance and recovery considerations for your system. To understand these considerations, see Chapter 13. Database Recovery Considerations.

Checking Changes to the Record Format Description

LVLCHK Parameter. The system checks, when you open the le, if the description of the record format you are using was changed since the program was compiled to an extent that your program cannot process the le. The system normally noties your program of this condition. This condition is known as a level check. When you use the create or change le commands, you can specify that you want level checking. You can also override the level check attribute dened for the le using the LVLCHK parameter on the Override with Database File (OVRDBF) command. For more information about this parameter, see Effect of Changing Fields in a File Description on page 199.

Checking for the Expiration Date of the File

EXPDATE and EXPCHK Parameters. The system can verify that the data in the le you specify is still current. You can specify the expiration date for a le or member using the EXPDATE parameter on the create and change le commands, and you can specify whether or not the system is to check that date using the EXPCHK parameter on the Override with Database File (OVRDBF) command. If you do check the expiration date and the current date is greater than the expiration date, a message is sent to the system operator when the le is opened.

Preventing the Job from Changing Data in the File

INHWRT Parameter. If you want to test your program, but do not want to actually change data in les used for the test, you can tell the system to not write (inhibit) any changes to the le that the program attempts to make. To inhibit any changes to the le, specify INHWRT(*YES) on the Override with Database File (OVRDBF) command.

Sharing Database Files Across Jobs

By denition, all database les can be used by many users at the same time. However, some operations can lock the le, member, or data records in a member to prevent the le, member, or data records from being shared across jobs.

102

OS/400 DB2 for AS/400 Database Programming V4R3

Each database command or high-level language program allocates the le, member, and data records that it uses. Depending on the operation requested, other users will not be able to use the allocated le, member, or records. An operation on a logical le or logical le member can allocate the le(s) and member(s) that the logical le depends on for data or an access path. For example, the open of a logical le allocates the data of the physical le member that the logical le is based on. If the program updates the logical le member, another user may not request, at the same time, that the physical le member used by that logical le member be cleared of data. For a list of commonly used database functions and the types of locks they place on database les, see Appendix C. Database Lock Considerations.

Record Locks
WAITRCD Parameter. The AS/400 database has built-in integrity for records. For example, if PGMA reads a record for update, it locks that record. Another program may not read the same record for update until PGMA releases the record, but another program could read the record just for inquiry. In this way, the system ensures the integrity of the database. The system determines the lock condition based on the type of le processing specied in your program and the operation requested. For example, if your open options include update or delete, each record read is locked so that any number of users can read the record at the same time, but only one user can update the record. The system normally waits a specic number of seconds for a locked record to be released before it sends your program a message that it cannot get the record you are requesting. The default record wait time is 60 seconds; however, you can set your own wait time through the WAITRCD parameter on the create and change le commands and the override database le command. If your program is notied that the record it wants is locked by another operation, you can have your program take the appropriate action (for example, you could send a message to the operator that the requested record is currently unavailable). The system automatically releases a lock when the locked record is updated or deleted. However, you can release record locks without updating the record. For information on how to release a record lock, see your high-level language guide. Note: Using commitment control changes the record locking rules. See the Backup and Recovery book for more information on commitment control and its effect on the record locking rules. You can use the Display Record Locks (DSPRCDLCK) command to display the current lock status (wait or held) of records for a physical le member. The command will also indicate what type of lock is currently held. (For more information about lock types, see the Backup and Recovery book.) Depending on the parameters you specify, this command displays the lock status for a specic record or displays the lock status of all records in the member. You can also display record locks from the Work with Job (WRKJOB) display. You can determine if your job currently has any records locked using the Check Record Lock (CHKRCDLCK) command. This command returns a message (which you can monitor) if your job has any locked records. The command is useful if you
Chapter 5. Run Time Considerations

103

are using group jobs. For example, you could check to see if you had any records locked, before transferring to another group job. If you determined you did have records locked, your program could release those locks.

File Locks
WAITFILE Parameter. Some le operations exclusively allocate the le for the length of the operation. During the time the le is allocated exclusively, any program trying to open that le has to wait until the le is released. You can control the amount of time a program waits for the le to become available by specifying a wait time on the WAITFILE parameter of the create and change le commands and the override database le command. If you do not specically request a wait time, the system defaults the le wait time to zero seconds. A le is exclusively allocated when an operation that changes its attributes is run. These operations (such as move, rename, grant or revoke authority, change owner, or delete) cannot be run at the same time with any other operation on the same le or on members of that le. Other le operations (such as display, open, dump, or check object) only use the le denition, and thus lock the le less exclusively. They can run at the same time with each other and with input/output operations on a member.

Member Locks
Member operations (such as add and remove) automatically allocate the le exclusively enough to prevent other le operations from occurring at the same time. Input/output operations on the same member cannot be run, but input/output operations on other members of the same le can run at the same time.

Record Format Data Locks

RCDFMTLCK Parameter. If you want to lock the entire set of records associated with a record format (for example, all the records in a physical le), you can use the RCDFMTLCK parameter on the OVRDBF command.

Sharing Database Files in the Same Job or Activation Group

SHARE Parameter. By default, the database management system lets one le be read and changed by many users at the same time. You can also share a le in the same job or activation group by opening the database le: v More than once in the same program. v In different programs in the same job or activation group. Note: For more information on open sharing in the Integrated Language Environment see the International Application Development book. The SHARE parameter on the create le, change le, and override database le commands allow sharing in a job or activation group, including sharing the le, its status, its positions, and its storage area. Sharing les in the job or activation group can improve performance by reducing the amount of main storage needed and by reducing the time needed to open and close the le.

104

OS/400 DB2 for AS/400 Database Programming V4R3

Using the SHARE(*YES) parameter lets two or more programs running in the same job or activation group share an open data path (ODP). An open data path is the path through which all input/output operations for the le are performed. In a sense, it connects the program to a le. If you do not specify the SHARE(*YES) parameter, a new open data path is created every time a le is opened. If an active le is opened more than once in the same job or activation group, you can use the active ODP for the le with the current open of the le. You do not have to create a new open data path. This reduces the amount of time required to open the le after the rst open, and the amount of main storage required by the job or activation group. SHARE(*YES) must be specied for the rst open and other opens of the same le for the open data path to be shared. A well-designed (for performance) application normally shares an open data path with les that are opened in multiple programs in the same job or activation group. Specifying SHARE(*NO) tells the system not to share the open data path for a le. Normally, this is specied only for those les that are seldom used or require unique processing in specic programs. Note: A high-level language program processes an open or a close operation as though the le were not being shared. You do not specify that the le is being shared in the high-level language program. You indicate that the le is being shared in the same job or activation group through the SHARE parameter. The SHARE parameter is specied only on the create, change, and override database le commands.

Open Considerations for Files Shared in a Job or Activation Group

Consider the following items when you open a database le that is shared in the same job or activation group. v Make sure that when the shared le is opened for the rst time in a job or activation group, all the open options needed for subsequent opens of the le are specied. If the open options specied for subsequent opens of a shared le do not match those specied for the rst open of a shared le, an error message is sent to the program. (You can correct this by making changes to your program or to the OPNDBF or OPNQRYF command parameters, to remove any incompatible options.) For example, PGMA is the rst program to open FILE1 in the job or activation group and PGMA only needs to read the le. However, PGMA calls PGMB, which will delete records from the same shared le. Because PGMB will delete records from the shared le, PGMA will have to open the le as if it, PGMA, is also going to delete records. You can accomplish this by using the correct specications in the high-level language. (To accomplish this in some high-level languages, you may have to use le operation statements that are never run. See your high-level language guide for more details.) You can also specify the le processing option on the OPTION parameter on the Open Database File (OPNDBF) and Open Query File (OPNQRYF) commands. v Sometimes sharing a le within a job or activation group is not desirable. For example, one program can need records from a le in arrival sequence and another program needs the records in keyed sequence. In this situation, you should not share the open data path. You would specify SHARE(*NO) on the Override with Database File (OVRDBF) command to ensure the le was not shared within the job or activation group.
Chapter 5. Run Time Considerations

105

v If debug mode is entered with UPDPROD(*NO) after the rst open of a shared le in a production library, subsequent shared opens of the le share the original open data path and allow the le to be changed. To prevent this, specify SHARE(*NO) on the OVRDBF command before opening les being debugged. v The use of commitment control for the rst open of a shared le requires that all subsequent shared opens also use commitment control. v Key feedback, insert key feedback, or duplicate key feedback must be specied on the full open if any of these feedback types are desired on the subsequent shared opens of the le. v If you did not specify a library name in the program or on the Override with Database File (OVRDBF) command (*LIBL is used), the system assumes the library list has not changed since the last open of the same shared le with *LIBL specied. If the library list has changed, you should specify the library name on the OVRDBF command to ensure the correct le is opened. v The record length that is specied on the full open is the record length that is used on subsequent shared opens even if a larger record length value is specied on the shared opens of the le. v Overrides and program specications specied on the rst open of the shared le are processed. Overrides and program specications specied on subsequent opens, other than those that change the le name or the value specied on the SHARE or LVLCHK parameters on the OVRDBF command, are ignored. v Overrides specied for a rst open using the OPNQRYF command can be used to change the names of the les, libraries, and members that should be processed by the Open Query File command. Any parameter values specied on the Override with Database File (OVRDBF) command other than TOFILE, MBR, LVLCHK, and SEQONLY are ignored by the OPNQRYF command. v The Open Database File (OPNDBF) and Open Query File (OPNQRYF) commands scope the ODP to the level specied on the Open Scope (OPNSCOPE) parameter according to the following: The system searches for shared opens in the activation group rst, and then in the job. Shared opens that are scoped to an activation group may not be shared between activation groups. Shared opens that are scoped to the job can be shared throughout the job, by any number of activation groups at a time. The CPF4123 diagnostic message lists the mismatches that can be encountered between the full open and the subsequent shared opens. These mismatches do not cause the shared open to fail. Note: The Open Query File (OPNQRYF) command never shares an existing shared open data path in the job or activation group. If a shared ODP already exists in the job or activation group with the same le, library, and member name as the one specied on the Open Query File command, the system sends an error message and the query le is not opened.

Input/Output Considerations for Files Shared in a Job or Activation Group

Consider the following items when processing a database le that is shared in the same job or activation group. v Because only one open data path is allowed for a shared le, only one record position is maintained for all programs in the job or activation group that is

106

OS/400 DB2 for AS/400 Database Programming V4R3

sharing the le. If a program establishes a position for a record using a read or a read-for-update operation, then calls another program that also uses the shared le, the record position may have moved or a record lock been released when the called program returns to the calling program. This can cause errors in the calling program because of an unexpected record position or lock condition. When sharing les, it is your responsibility to manage the record position and record locking considerations by re-establishing position and locks. v If a shared le is rst opened for update, this does not necessarily cause every subsequent program that shares the le to request a record lock. The system determines the type of record lock needed for each program using the le. The system tries to keep lock contention to a minimum, while still ensuring data integrity. For example, PGMA is the rst program in the job or activation group to open a shared le. PGMA intends to update records in the le; therefore, when the program reads a record for update, it will lock the record. PGMA then calls PGMB. PGMB also uses the shared le, but it does not update any records in the le; PGMB just reads records. Even though PGMA originally opened the shared le as update-capable, PGMB will not lock the records it reads, because of the processing specications in PGMB. Thus, the system ensures data integrity, while minimizing record lock contention.

Close Considerations for Files Shared in a Job or Activation Group

Consider the following items when closing a database le that is shared in the same job or activation group. v The complete processing of a close operation (including releasing le, member, and record locks; forcing changes to auxiliary storage; and destroying the open data path) is done only when the last program to open the shared open data path closes it. v If the le was opened with the Open Database File (OPNDBF) or the Open Query File (OPNQRYF) command, use the Close File (CLOF) command to close the le. The Reclaim Resources (RCLRSC) command can be used to close a le opened by the Open Query File (OPNQRYF) command when one of the following is specied: OPNSCOPE(*ACTGRPDFN), and the open is requested from the default activation group. TYPE(*NORMAL) is specied. If one of the following is specied, the le remains open even if the Reclaim Resources (RCLRSC) command is run: OPNSCOPE(*ACTGRPDFN), and the open is requested from some activation group other than the default OPNSCOPE(*ACTGRP) OPNSCOPE(*JOB) TYPE(*PERM)

Examples of Closing Shared Files

The following examples show some of the things to consider when closing a le that is shared in the same job. Example 1: Using a single set of les with similar processing options.
Chapter 5. Run Time Considerations

107

In this example, the user signs on and most of the programs used process the same set of les. A CL program (PGMA) is used as the rst program (to set up the application, including overrides and opening the shared les). PGMA then transfers control to PGMB, which displays the application menu. Assume, in this example, that les A, B, and C are used, and les A and B are to be shared. Files A and B were created with SHARE(*NO); therefore an OVRDBF command should precede each of the OPNDBF commands to specify the SHARE(*YES) option. File C was created with SHARE(*NO) and File C is not to be shared in this example.
PGMA: PGM OVRDBF OVRDBF OPNDBF OPNDBF TFRCTL ENDPGM /* PGMA FILE(A) FILE(B) FILE(A) FILE(B) PGMB - Initial program SHARE(*YES) SHARE(*YES) OPTION(*ALL) .... OPTION(*INP) ... */

PGMB:

PGM DCLF BEGIN: SNDRCVF IF IF . . IF GOTO ENDPGM

/* PGMB - Menu program */ FILE(DISPLAY) RCDFMT(MENU) (&RESPONSE *EQ '1') CALL PGM11 (&RESPONSE *EQ '2') CALL PGM12 (&RESPONSE *EQ '90') SIGNOFF BEGIN

The les opened in PGMA are either scoped to the job, or PGMA, PGM11, and PGM12 run in the same activation group and the le opens are scoped to that activation group. In this example, assume that: v PGM11 opens les A and B. Because these les were opened as shared by the OPNDBF commands in PGMA, the open time is reduced. The close time is also reduced when the shared open data path is closed. The Override with Database File (OVRDBF) commands remain in effect even though control is transferred (with the Transfer Control [TFRCTL] command in PGMA) to PGMB. v PGM12 opens les A, B, and C. File A and B are already opened as shared and the open time is reduced. Because le C is used only in this program, the le is not opened as shared. In this example, the Close File (CLOF) was not used because only one set of les is required. When the operator signs off, the les are automatically closed. It is assumed that PGMA (the initial program) is called only at the start of the job. For information on how to reclaim resources in the Integrated Language Environment, see the ILE Concepts book. Note: The display le (DISPLAY) in PGMB can also be specied as a shared le, which would improve the performance for opening the display le in any programs that use it later. In Example 1, the OPNDBF commands are placed in a separate program (PGMA) so the other processing programs in the job run as efficiently as possible. That is, the important les used by the other programs in the job are opened in PGMA.

108

OS/400 DB2 for AS/400 Database Programming V4R3

After the les are opened by PGMA, the main processing programs (PGMB, PGM11, and PGM12) can share the les; therefore, their open and close requests will process faster. In addition, by placing the open commands (OPNDBF) in PGMA rather than in PGMB, the amount of main storage used for PGMB is reduced. Any overrides and opens can be specied in the initial program (PGMA); then, that program can be removed from the job (for example, by transferring out of it). However, the open data paths that the program created when it opened the les remain in existence and can be used by other programs in the job. Note the handling of the OVRDBF commands in relation to the OPNDBF commands. Overrides must be specied before the le is opened. Some of the parameters on the OVRDBF command also exist on the OPNDBF command. If conicts arise, the OVRDBF value is used. For more information on when overrides take effect in the Integrated Language Environment, see the ILE Concepts book. Example 2: Using multiple sets of les with similar processing options. Assume that a menu requests the operator to specify the application program (for example, accounts receivable or accounts payable) that uses the Open Database File (OPNDBF) command to open the required les. When the application is ended, the Close File (CLOF) command closes the les. The CLOF command is used to help reduce the amount of main storage needed by the job. In this example, different les are used for each application. The user normally works with one application for a considerable length of time before selecting a new application. An example of the accounts receivable programs follows:
PGMC: PGM DCLF BEGIN: SNDRCVF IF IF . . IF GOTO ENDPGM /* PGMC PROGRAM */ FILE(DISPLAY) RCDFMT(TOPMENU) (&RESPONSE *EQ '1') CALL ACCRECV (&RESPONSE *EQ '2') CALL ACCPAY (&RESPONSE *EQ '90') SIGNOFF BEGIN

ACCREC: PGM DCLF OVRDBF OVRDBF OPNDBF OPNDBF BEGIN: SNDRCVF IF IF . . IF

/* ACCREC PROGRAM */ FILE(DISPLAY) FILE(A) SHARE(*YES) FILE(B) SHARE(*YES) FILE(A) OPTION(*ALL) .... FILE(B) OPTIONS(*INP) ... RCDFMT(ACCRMENU) (&RESPONSE *EQ '1') CALL PGM21 (&RESPONSE *EQ '2') CALL PGM22 (&RESPONSE *EQ '88') DO /* Return */ CLOF FILE(A) CLOF FILE(B) RETURN ENDDO BEGIN

GOTO ENDPGM

Chapter 5. Run Time Considerations

109

The program for the accounts payable menu would be similar, but with a different set of OPNDBF and CLOF commands. For this example, les A and B were created with SHARE(*NO). Therefore, an OVRDBF command must precede the OPNDBF command. As in Example 1, the amount of main storage used by each job could be reduced by placing the OPNDBF commands in a separate program and calling it. A separate program could also be created for the CLOF commands. The OPNDBF commands could be placed in an application setup program that is called from the menu, which transfers control to the specic application program menu (any overrides specied in this setup program are kept). However, calling separate programs for these functions also uses system resources and, depending on the frequency with which the different menus are used, it can be better to include the OPNDBF and CLOF commands in each application program menu as shown in this example. Another choice is to use the Reclaim Resources (RCLRSC) command in PGMC (the setup program) instead of using the Close File (CLOF) commands. The RCLRSC command closes any les and frees any leftover storage associated with any les and programs that were called and have since returned to the calling program. However, RCLRSC does not close les that are opened with the following specied on the Open Database File (OPNDBF) or Open Query File (OPNQRYF) commands: v OPNSCOPE(*ACTGRPDFN), and the open is requested from some activation group other than the default. v OPNSCOPE(*ACTGRP) reclaims if the RCLRSC command is from an activation group with an activation group number that is lower than the activation group number of the open. v OPNSCOPE(*JOB). v TYPE(*PERM). The following example shows the RCLRSC command used to close les:
. . IF (&RESPONSE *EQ '1') DO CALL ACCRECV RCLRSC ENDDO (&RESPONSE *EQ '2') DO CALL ACCPAY RCLRSC ENDDO

IF

. .

Example 3: Using a single set of les with different processing requirements. If some programs need read-only le processing and others need some or all of the options (input/update/add/delete), one of the following methods can be used. The same methods apply if a le is to be processed with certain command parameters in some programs and not in others (for example, sometimes the commit option should be used). A single Open Database File (OPNDBF) command could be used to specify OPTION(*ALL) and the open data path would be opened shared (if, for example, a previous OVRDBF command was used to specify SHARE(*YES)). Each program could then open a subset of the options. The program requests the type of open depending on the specications in the program. In some cases this does not require any more considerations because a program specifying an open for input only

110

OS/400 DB2 for AS/400 Database Programming V4R3

would operate similarly as if it had not done a shared open (for example, no additional record locking occurs when a record is read). However, some options specied on the OPNDBF command can affect how the program operates. For example, SEQONLY(*NO) is specied on the open command for a le in the program. An error would occur if the OPNDBF command used SEQONLY(*YES) and a program attempted an operation that was not valid with sequential-only processing. The ACCPTH parameter must also be consistent with the way programs will use the access path (arrival or keyed). If COMMIT(*YES) is specied on the Open Database File (OPNDBF) command and the Start Commitment Control (STRCMTCTL) command species LCKLVL(*ALL) or LCKLVL(*CS), any read operation of a record locks that record (per commitment control record locking rules). This can cause records to be locked unexpectedly and cause errors in the program. Two OPNDBF commands could be used for the same data (for example, one with OPTION(*ALL) and the other specifying OPTION(*INP)). The second use must be a logical le pointing to the same physical le(s). This logical le can then be opened as SHARE(*YES) and multiple uses made of it during the same job.

Sequential-Only Processing
SEQONLY and NBRRCDS Parameters. If your program processes a database le sequentially for input only or output only, you might be able to improve performance using the sequential-only processing (SEQONLY) parameter on the Override with Database File (OVRDBF) or the Open Database File (OPNDBF) commands. To use SEQONLY processing, the le must be opened for input-only or output-only. The NBRRCDS parameter can be used with any combination of open options. (The Open Query File [OPNQRYF] command uses sequential-only processing whenever possible.) Depending on your high-level language specications, the high-level language can also use sequential-only processing as the default. For example, if you open a le for input only and the only le operations specied in the high-level language program are sequential read operations, then the high-level language automatically requests sequential-only processing. Note: File positioning operations are not considered sequential read operations; therefore, a high-level language program containing positioning operations will not automatically request sequential-only processing. (The SETLL operation in the RPG/400 language and the START operation in the COBOL/400* language are examples of le positioning operations.) Even though the high-level language program can not automatically request sequential-only processing, you can request it using the SEQONLY parameter on the OVRDBF command. If you specify sequential-only processing, you can also specify the number of records to be moved as one unit between the system database main storage area and the jobs internal data main storage area. If you do not specify the sequential-only number of records to be moved, the system calculates a number based on the number of records that t into a 4096-byte buffer.

Chapter 5. Run Time Considerations

111

The system also provides you a way to control the number of records that are moved as a unit between auxiliary storage and main storage. If you are reading the data in the le in the same order as the data is physically stored, you can improve the performance of your job using the NBRRCDS parameter on the OVRDBF command. Note: Sequential-only processing should not be used with a keyed sequence access path le unless the physical data is in the same order as the access path. SEQONLY(*YES) processing may cause poor application performance until the physical data is reorganized into the access paths order.

Open Considerations for Sequential-Only Processing

The following considerations apply for opening les when sequential-only processing is specied. If the system determines that sequential-only processing is not allowed, a message is sent to the program to indicate that the request for sequential-only processing is not being accepted; however, the le is still opened for processing. v If the program opened the member for output only, and if SEQONLY(*YES) was specied (number of records was not specied) and either the opened member is a logical member, a uniquely keyed physical member, or there are other access paths to the physical member, SEQONLY(*YES) is changed to SEQONLY(*NO) so the program can handle possible errors (for example, duplicate keys, conversion mapping, and select/omit errors) at the time of the output operation. If you want the system to run sequential-only processing, change the SEQONLY parameter to include both the *YES value and number of records specication. v Sequential-only processing can be specied only for input-only (read) or output-only (add) operations. If the program species update or delete operations, sequential-only processing is not allowed by the system. v If a le is being opened for output, it must be a physical le or a logical le based on one physical le member. v Sequential-only processing can be specied with commitment control only if the member is opened for output-only. v If sequential-only processing is being used for les opened with commitment control and a rollback operation is performed for the job, the records that reside in the jobs storage area at the time of the rollback operation are not written to the system storage area and never appear in the journal for the commitment control transaction. If no records were ever written to the system storage area prior to a rollback operation being performed for a particular commitment control transaction, the entire commitment control transaction is not reected in the journal. v For output-only, the number of records specied to be moved as a unit and the force ratio are compared and automatically adjusted as necessary. If the number of records is larger than the force ratio, the number of records is reduced to equal the force ratio. If the opposite is true, the force ratio is reduced to equal the number of records. v If the program opened the member for output only, and if SEQONLY(*YES) was specied (number of records was not specied), and duplicate or insert key feedback has been requested, SEQONLY(*YES) will be changed to SEQONLY(*NO) to provide the feedback on a record-by-record basis when the records are inserted into the le. v The number of records in a block will be changed to one if all of the following are true:

112

OS/400 DB2 for AS/400 Database Programming V4R3

 The member was opened for output-only processing. No override operations are in effect that have specied sequential-only processing. The le being opened is a le that cannot be extended because its increment number of records was set to zero. The number of bytes available in the le is less than the number of bytes that t into a block of records. The following considerations apply when sequential-only processing is not specied and the le is opened using the Open Query File (OPNQRYF) command. If these conditions are satised, a message is sent to indicate that sequential-only processing will be performed and the query le is opened. v If the OPNQRYF command species the name of one or more elds on the group eld (GRPFLD) parameter, or OPNQRYF requires group processing. v If the OPNQRYF command species one or more elds, or *ALL on the UNIQUEKEY parameter. v If a view is used with the DISTINCT option on the SQL SELECT statement, then SEQONLY(*YES) processing is automatically performed. For more details about the OPNQRYF command, see Using the Open Query File (OPNQRYF) Command on page 121.

Input/Output Considerations for Sequential-Only Processing

The following considerations apply for input/output operations on les when sequential-only processing is specied. v For input, your program receives one record at a time from the input buffer. When all records in the input buffer are processed, the system automatically reads the next set of records. Note: Changes made after records are read into the input buffer are not reected in the input buffer. v For output, your program must move one record at a time to the output buffer. When the output buffer is full, the system automatically adds the records to the database. Note: If you are using a journal, the entire buffer is written to the journal at one time as if the entries had logically occurred together. This journal processing occurs before the records are added to the database. If you use sequential-only processing for output, you might not see all the changes made to the le as they occur. For example, if sequential-only is specied for a le being used by PGMA, and PGMA is adding new records to the le and the SEQONLY parameter was specied with 5 as the number of records in the buffer, then only when the buffer is lled will the newly added records be transferred to the database. In this example, only when the fth record was added, would the rst ve records be transferred to the database, and be available for processing by other jobs in the system. In addition, if you use sequential-only processing for output, some additions might not be made to the database if you do not handle the errors that could occur when records are moved from the buffer to the database. For example, assume the buffer holds ve records, and the third record in the buffer had a key
Chapter 5. Run Time Considerations

113

that was a duplicate of another record in the le and the le was dened as a unique-key le. In this case, when the system transfers the buffer to the database it would add the rst two records and then get a duplicate key error for the third. Because of this error, the third, fourth, and fth records in the buffer would not be added to the database. v The force-end-of-data function can be used for output operations to force all records in the buffer to the database (except those records that would cause a duplicate key in a le dened as having unique keys, as described previously). The force-end-of-data function is only available in certain high-level languages. v The number of records in a block will be changed to one if all of the following are true: The member was opened for output-only processing or sequential-only processing. No override operations are in effect that have specied sequential-only processing. The le being opened is being extended because the increment number of records was set to zero. The number of bytes available in the le is less than the number of bytes that t into a block of records.

Close Considerations for Sequential-Only Processing

When a le for which sequential-only processing is specied is closed, all records still in the output buffer are added to the database. However, if an error occurs for a record, any records following that record are not added to the database. If multiple programs in the same job are sharing a sequential-only output le, the output buffer is not emptied until the nal close occurs. Consequently, a close (other than the last close in the job) does not cause the records still in the buffer to appear in the database for this or any other job.

Run Time Summary

The following tables list parameters that control your programs use of the database le member, and indicates where these parameters can be specied. For parameters that can be specied in more than one place, the system merges the values. The Override with Database File (OVRDBF) command parameters take precedence over program parameters, and Open Database File (OPNDBF) or Open Query File (OPNQRYF) command parameters take precedence over create or change le parameters. Note: Any override parameters other than TOFILE, MBR, LVLCHK, SEQONLY, SHARE, WAITRCD, and INHWRT are ignored by the OPNQRYF command. A table of database processing options specied on control language (CL) commands is shown below:
Table 5. Database Processing Options Specied on CL Commands Command Description File name Parameter FILE CRTPF, CRTLF X CHGPF, CHGLF X1 OPNDBF X OPNQRYF X OVRDBF X

114

OS/400 DB2 for AS/400 Database Programming V4R3

Table 5. Database Processing Options Specied on CL Commands (continued) Command Description Library name Member name MBR Member processing options Record format lock state Starting le position after open Program performs only sequential processing Ignore keyed sequence access path Time to wait for le locks Time to wait for record locks Prevent overrides Number of records to be transferred from auxiliary to main storage OPTION Parameter CRTPF, CRTLF X X CHGPF, CHGLF X
2

OPNDBF X X X

OPNQRYF X X X

OVRDBF X X

RCDFMTLCK POSITION

X X

SEQONLY

ACCPTH

WAITFILE WAITRCD

X X

X X

X X

SECURE NBRRCDS

X X

SHARE Share open data path with other programs Format selector Force ratio Inhibit write FMTSLR FRCRATIO INHWRT

X3 X

X3 X

X X X

Level check LVLCHK record formats Expiration date checking EXPCHK

X X

Chapter 5. Run Time Considerations

115

Table 5. Database Processing Options Specied on CL Commands (continued) Command Description Expiration date Force access path Commitment control End-of-le delay Duplicate key check Reuse deleted record space Coded character set identier Sort Sequence Language identier Notes:
1

Parameter EXPDATE FRCACCPTH COMMIT EOFDLY DUPKEYCHK REUSEDLT CCSID

CRTPF, CRTLF X
4

CHGPF, CHGLF X
4

OPNDBF

OPNQRYF

OVRDBF X

X X X X X X

X4 X4

X4 X4

SRTSEQ LANGID

X X

X X

X X

File name: The CHGPF and CHGLF commands use the le name for identication only. You cannot change the le name. Library name: The CHGPF and CHGLF commands use the library name for identication only. You cannot change the library name. Format selector: Used on the CRTLF and CHGLF commands only. Expiration date, reuse deleted records, and coded character set identier: Used on the CRTPF and CHGPF commands only.

3 4

A table of database processing options specied in programs is shown below:

Table 6. Database Processing Options Specied in Programs Description File name Library name Member name Program record length Member processing options Record format lock state X X X X RPG/400 Language X COBOL/400 Language X AS/400 BASIC X X X X X AS/400 PL/I X X X X X AS/400 Pascal X X X X X

116

OS/400 DB2 for AS/400 Database Programming V4R3

Table 6. Database Processing Options Specied in Programs (continued) Description Record formats the program will use Clear physical le member of records Program performs only sequential processing Ignore keyed sequence access path Share open data path with other programs Level check record formats Commitment control Duplicate key check X X X X X X X RPG/400 Language X COBOL/400 Language AS/400 BASIC X AS/400 PL/I AS/400 Pascal

X X

: Control language (CL) programs can also specify many of these parameters. See Table 5 on page 114 for more information about the database processing options that can be specied on CL commands.

Storage Pool Paging Option Effect on Database Performance

The Paging option of shared pools can have a signicant impact on the performance of reading and changing database les. v A paging option of *FIXED causes the program to minimize the amount of memory it uses by: Transferring data from auxiliary storage to main memory in smaller blocks Writing le changes (updates to existing records or newly added records) to auxiliary storage frequently This option allows the system to perform much like it did before the paging option was added. v A paging option of *CALC may improve how the program performs when it reads and updates database les. In cases where there is sufficient memory available within a shared pool, the program may: Transfer larger blocks of data to memory from auxiliary storage. Write changed data to auxiliary storage less frequently. The paging operations done on database les vary dynamically based on le use and memory availability. Frequently referenced les are more likely to remain

Chapter 5. Run Time Considerations

117

resident than those less often accessed. The memory is used somewhat like a cache for popular data. The overall number of I/O operations may be reduced using the *CALC paging option. For more information on the paging option see the Work Management book.

118

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 6. Opening a Database File

This chapter discusses opening a database le. In addition, the CL commands Open Database File (OPNDBF) and Open Query File (OPNQRYF) are discussed.

Opening a Database File Member

To use a database le in a program, your program must issue an open operation to the database le. If you do not specify an open operation in some programming languages, they automatically open the le for you. If you did not specify a member name in your program or on an Override with Database File (OVRDBF) command, the rst member (as dened by creation date and time) in the le is used. If you specify a member name, les that have the correct le name but do not contain the member name are ignored. If you have multiple database les named FILEA in different libraries, the member that is opened is the rst one in the library list that matches the request. For example, LIB1, LIB2, and LIB3 are in your library list and all three contain a le named FILEA. Only FILEA in LIB3 has a member named MBRA that is to be opened. Member MRBA in FILEA in LIB3 is opened; the other FILEAs are ignored. After nding the member, the system connects your program to the database le. This allows your program to perform input/output operations to the le. For more information about opening les in your high-level language program, see the appropriate high-level language guide. You can open a database le with statements in your high-level language program. You can also use the CL open commands: Open Database File (OPNDBF) and Open Query File (OPNQRYF). The OPNDBF command is useful in an initial program in a job for opening shared les. The OPNQRYF command is very effective in selecting and arranging records outside of your program. Then, your program can use the information supplied by the OPNQRYF command to process only the data it needs.

Using the Open Database File (OPNDBF) Command

Usually, when you use the OPNDBF command, you can use the defaults for the command parameter values. In some instances you may want to specify particular values, instead of using the default values, for the following parameters: OPTION Parameter. Specify the *INP option if your application programs uses input-only processing (reading records without updating records). This allows the system to read records without trying to lock each one for possible update. Specify the *OUT option if your application programs uses output-only processing (writing records into a le but not reading or updating existing records). Note: If your program does direct output operations to active records (updating by relative record number), *ALL must be specied instead of *OUT. If your program does direct output operations to deleted records only, *OUT must be specied.

Copyright IBM Corp. 1997, 1998

119

MBR Parameter. If a member, other than the rst member in the le, is to be opened, you must specify the name of the member to be opened or issue an Override with Database File (OVRDBF) command before the Open Database File (OPNDBF) command. Note: You must specify a member name on the OVRDBF command to use a member (other than the rst member) to open in subsequent programs. OPNID Parameter. If an identier other than the le name is to be used, you must specify it. The open identier can be used in other CL commands to process the le. For example, the Close File (CLOF) command uses the identier to specify which le is to be closed. ACCPTH Parameter. If the le has a keyed sequence access path and either (1) the open option is *OUT, or (2) the open option is *INP or *ALL, but your program does not use the keyed sequence access path, then you can specify ACCPTH(*ARRIVAL) on the OPNDBF parameter. Ignoring the keyed sequence access path can improve your jobs performance. SEQONLY Parameter. Specify *YES if subsequent application programs process the le sequentially. This parameter can also be used to specify the number of records that should be transferred between the system data buffers and the program data buffers. SEQONLY(*YES) is not allowed unless OPTION(*INP) or OPTION(*OUT) is also specied on the Open Database File (OPNDBF) command. Sequential-only processing should not be used with a keyed sequence access path le unless the physical data is in access path order. COMMIT Parameter. Specify *YES if the application programs use commitment control. If you specify *YES you must be running in a commitment control environment (the Start Commitment Control [STRCMTCTL] command was processed) or the OPNDBF command will fail. Use the default of *NO if the application programs do not use commitment control. OPNSCOPE Parameter. Species the scoping of the open data path (ODP). Specify *ACTGRPDFN if the request is from the default activation group, and the ODP is to be scoped to the call level of the program issuing the command. If the request is from any other activation group, the ODP is scoped to that activation group. Specify *ACTGRP if the ODP is to be scoped to the activation group of the program issuing the command. Specify *JOB if the ODP is to be scoped to the job. If you specify this parameter and the TYPE parameter you get an error message. DUPKEYCHK Parameter. Specify whether or not you want duplicate key feedback. If you specify *YES, duplicate key feedback is returned on I/O operations. If you specify *NO, duplicate key feedback is not returned on I/O operations. Use the default (*NO) if the application programs are not written in the COBOL/400 language or C/400* language, or if your COBOL or C programs do not use the duplicate-key feedback information that is returned. TYPE Parameter. Specify what you wish to happen when exceptions that are not monitored occur in your application program. If you specify *NORMAL one of the following can happen: v Your program can issue a Reclaim Resources (RCLRSC) command to close the les opened at a higher level in the call stack than the program issuing the RCLRSC command. v The high-level language you are using can perform a close operation.

120

OS/400 DB2 for AS/400 Database Programming V4R3

Specify *PERM if you want to continue the application without opening the les again. TYPE(*NORMAL) causes les to be closed if both of the following occur: v Your program receives an error message v The les are opened at a higher level in the call stack. TYPE(*PERM) allows the les to remain open even if an error message is received. Do not specify this parameter if you specied the OPNSCOPE parameter.

Using the Open Query File (OPNQRYF) Command

The Open Query File (OPNQRYF) command is a CL command that allows you to perform many data processing functions on database les. Essentially, the OPNQRYF command acts as a lter between the processing program and the database records. The database le can be a physical or logical le. Unlike a database le created with the Create Physical File (CRTPF) command or the Create Logical File (CRTLF) command, the OPNQRYF command creates only a temporary le for processing the data, it does not create a permanent le. To understand the OPNQRYF command support, you should already be familiar with database concepts such as physical and logical les, key elds, record formats, and join logical les. The OPNQRYF command has functions similar to those in DDS, and the CRTPF and CRTLF commands. DDS requires source statements and a separate step to create the le. OPNQRYF allows a dynamic denition without using DDS. The OPNQRYF command does not support all of the DDS functions, but it supports signicant functions that go beyond the capabilities of DDS. In addition, Query/400 can be used to perform some of the function the OPNQRYF command performs. However, the OPNQRYF command is more useful as a programmers tool. The OPNQRYF command parameters also have many functions similar to the SQL SELECT statements. For example, the FILE parameter is similar to the SQL FROM statement, the QRYSLT parameter is similar to the SQL WHERE statement, the GRPFLD parameter is similar to the SQL GROUP BY statement, and the GRPSLT parameter is similar to the SQL HAVING statement. For more information about SQL, see the DB2 for AS/400 SQL Programming book. The following is a list of the major functions supplied by OPNQRYF. Each of these functions is described later in this section. v Dynamic record selection v v v v v Dynamic keyed sequence access path Dynamic keyed sequence access path over a join Dynamic join Handling missing records in secondary join les Unique-key processing

v Mapped eld denitions v Group processing v Final total-only processing v Improving performance v Open Query Identier (ID)
Chapter 6. Opening a Database File

121

v Sort sequence processing To understand the OPNQRYF command, you must be familiar with its two processing approaches: using a format in the le, and using a le with a different format. The typical use of the OPNQRYF command is to select, arrange, and format the data so it can be read sequentially by your high-level language program. See the CL Reference (Abridged) for OPNQRYF command syntax and parameter descriptions.

Using an Existing Record Format in the File

Assume you only want your program to process the records in which the Code eld is equal to D. You create the program as if there were only records with a D in the Code eld. That is, you do not code any selection operations in the program. You then run the OPNQRYF command, and specify that only the records with a D in the Code eld are to be returned to the program. The OPNQRYF command does the record selection and your program processes only the records that meet the selection values. You can use this approach to select a set of records, return records in a different sequence than they are stored, or both. The following is an example of using the OPNQRYF command to select and sequence records:
Database File Process OVRDBF Command FILE SHARE(*YES)

Process OPNQRYF Command

Create the high-level language program to process the database le as you would any normal program using externally described data. Only one format can be used, and it must exist in the le. Run the OVRDBF command specifying the le and member to be processed and SHARE(*YES). (If the member is permanently changed to SHARE(*YES) and the rst or only member is the one you want to use, this step is not necessary.)

122

OS/400 DB2 for AS/400 Database Programming V4R3

The OVRDBF command can be run after the OPNQRYF command, unless you want to override the le name specied in the OPNQRYF command. In this discussion and in the examples, the OVRDBF command is shown rst. Some restrictions are placed on using the OVRDBF command with the OPNQRYF command. For example, MBR(*ALL) causes an error message and the le is not opened. Refer to Considerations for Files Shared in a Job on page 169 for more information. 3 Run the OPNQRYF command, specifying the database le, member, format names, any selection options, any sequencing options, and the scope of inuence for the opened le. Call the high-level language program you created in step 1. Besides using a high-level language, the Copy from Query File (CPYFRMQRYF) command can also be used to process the le created by the OPNQRYF command. Other CL commands (for example, the Copy File [CPYF] and the Display Physical File Member [DSPPFM] commands) and utilities (for example, Query) do not work on les created with the OPNQRYF command. Close the le that you opened in step 3, unless you want the le to remain open. The Close File (CLOF) command can be used to close the le. Delete the override specied in step 2 with the Delete Override (DLTOVR) command. It may not always be necessary to delete the override, but the command is shown in all the examples for consistency.

5 6

Using a File with a Different Record Format

For more advanced functions of the Open Query File (OPNQRYF) command (such as dynamically joining records from different les), you must dene a new le that contains a different record format. This new le is a separate le from the one you are going to process. This new le contains the elds that you want to create with the OPNQRYF command. This powerful capability also lets you dene elds that do not currently exist in your database records, but can be derived from them. When you code your high-level language program, specify the name of the le with the different format so the externally described eld denitions of both existing and derived elds can be processed by the program. Before calling your high-level language program, you must specify an Override with Database File (OVRDBF) command to direct your program le name to the open query le. On the OPNQRYF command, specify both the database le and the new le with the special format to be used by your high-level language program. If the le you are querying does not have SHARE(*YES) specied, you must specify SHARE(*YES) on the OVRDBF command.

Chapter 6. Opening a Database File

123

Database File

Process OVRDBF Command FILE TOFILE SHARE(*YES) Create File with Different Format

Process OPNQRYF Command FILE FORMAT Mapped Field Definitions Create High-Level Language Program FILE

Call Your Program

Process CLOF Command

Process DLTOVR Command

RSLH299-4

Specify the DDS for the le with the different record format, and create the le. This le contains the elds that you want to process with your high-level language program. Normally, data is not contained in this le, and it does not require a member. You normally create this le as a physical le without keys. A eld reference le can be used to describe the elds. The record format name can be different from the record format name in the database le that is specied. You can use any database or DDM le for this function. The le could be a logical le and it could be indexed. It could have one or more members, with or without data.

124

OS/400 DB2 for AS/400 Database Programming V4R3

Create the high-level language program to process the le with the record format that you created in step 1. In this program, do not name the database le that contains the data. Run the Override with Database File (OVRDBF) command. Specify the name of the le with the different (new) record format on the FILE parameter. Specify the name of the database le that you want to query on the TOFILE parameter. You can also specify a member name on the MBR parameter. If the database member you are querying does not have SHARE(*YES) specied, you must also specify SHARE(*YES) on the OVRDBF command. Run the Open Query File (OPNQRYF) command. Specify the database le to be queried on the FILE parameter, and specify the name of the le with the different (new) format that was created in step 1 on the FORMAT parameter. Mapped eld denitions can be required on the OPNQRYF command to describe how to map the data from the database le into the format that was created in step 1. You can also specify selection options, sequencing options, and the scope of inuence for the opened le. Call the high-level language program you created in step 2. The rst le named in step 4 for the FILE parameter was opened with OPNQRYF as SHARE(*YES) and is still open. The le must be closed. The Close File (CLOF) command can be used. Delete the override that was specied in step 3.

5 6

The previous steps show the normal ow using externally described data. It is not necessary to create unique DDS and record formats for each OPNQRYF command. You can reuse an existing record format. However, all elds in the record format must be actual elds in the real database le or dened by mapped eld denitions. If you use program-described data, you can create the program at any time. You can use the le created in step 1 to hold the data created by the Open Query File (OPNQRYF) command. For example, you can replace step 5 with a high-level language processing program that copies data to the le with the different format, or you may use the Copy from Query File (CPYFRMQRYF) command. The Copy File (CPYF) command cannot be used. You can then follow step 5 with the CPYF command or Query.

OPNQRYF Examples
The following sections describe how to specify both the OPNQRYF parameters for each of the major functions discussed earlier and how to use the Open Query File command with your high-level language program. Notes: 1. If you run the OPNQRYF command from a command entry line with the OPNSCOPE(*ACTGRPDFN) or TYPE(*NORMAL) parameter option, error messages that occur after the OPNQRYF command successfully runs will not close the le. Such messages would have closed the le prior to Version 2 Release 3 when TYPE(*NORMAL) was used. The system automatically runs the Reclaim Resources (RCLRSC) command if an error message occurs, except for message CPF0001, which is sent when the system detects an error in the

Chapter 6. Opening a Database File

125

command. However, the RCLRSC command only closes les opened from the default activation group at a higher level in the call stack than the level at which the RCLRSC command was run. 2. After running a program that uses the Open Query File command for sequential processing, the le position is normally at the end of the le. If you want to run the same program or a different program with the same les, you must position the le or close the le and open it with the same OPNQRYF command. You can position the le with the Position Database File (POSDBF) command. In some cases, a high-level language program statement can be used.

CL Program Coding with the OPNQRYF Command

The Open Query File (OPNQRYF) command has three basic rules that can prevent coding errors. 1. Specify selection elds from a database le without an ampersand (&). Fields declared in the CL program with DCL or DCLF require the ampersand. 2. Enclose elds dened in the CL program with DCL or DCLF within single quotes (&testd, for example). 3. Enclose all parameter comparisons within double quotes when compared to character elds, single quotes when compared to numeric elds. In the following example, the elds INVCUS and INVPRD are dened as character data:
QRYSLT('INVCUS *EQ "' *CAT &K1CUST *CAT '" *AND + INVPRD *GE "' *CAT &LPRD *CAT '" *AND + INVPRD *LE "' *CAT &HPRD *CAT '"')

If the elds were dened numeric data, the QRYSLT paremeter could look like the following:
QRYSLT('INVCUS *EQ ' *CAT &K1CUST *CAT ' *AND + INVPRD *GE ' *CAT &LPRD *CAT ' *AND + INVPRD *LE ' *CAT &HPRD *CAT ' ')

The Zero Length Literal and the Contains (*CT) Function

The concept of a zero length literal was introduced in Version 2, Release 1, Modication 1. In the OPNQRYF command, a zero length literal is denoted as a quoted string with nothing, not even a blank, between the quotes (). Zero length literal support changes the results of a comparison when used as the compare argument of the contains (*CT) function. Consider the statement:
QRYSLT('field *CT ""')

With zero length literal support, the statement returns records that contain anything. It is, in essence, a wildcard comparison for any number of characters followed by any number of characters. It is equivalent to:
'field = %WLDCRD("**")'

Before zero length literal support, (before Version 2, Release 1, Modication 1), the argument () was interpreted as a single-byte blank. The statement returned records that contained a single blank somewhere in the eld. It was, in essence, a wildcard comparison for any number of characters, followed by a blank, followed by any number of characters. It was equivalent to:

126

OS/400 DB2 for AS/400 Database Programming V4R3

'field = %WLDCRD("* *")'

To Repeat Pre-Zero Length Literal Support Results

To get pre-Version 2, Release 1, Modication 1 results with the contains function, you must code the QRYSLT to explicitly look for the blank:
QRYSLT('field *CT " "')

Selecting Records without Using DDS

Dynamic record selection allows you to request a subset of the records in a le without using DDS. For example, you can select records that have a specic value or range of values (for example, all customer numbers between 1000 and 1050). The Open Query File (OPNQRYF) command allows you to combine these and other selection functions to produce powerful record selection capabilities.

Examples of Selecting Records Using the Open Query File (OPNQRYF) Command
In all of the following examples, it is assumed that a single-format database le (physical or logical) is being processed. (The FILE parameter on the OPNQRYF command allows you to specify a record format name if the le is a multiple format logical le.) See the OPNQRYF command in the CL Reference (Abridged) for a complete description of the format of expressions used with the QRYSLT parameter. Example 1: Selecting records with a specic value Assume you want to select all the records from FILEA where the value of the Code eld is D. Your processing program is PGMB. PGMB only sees the records that meet the selection value (you do not have to test in your program). Note: You can specify parameters easier by using the prompt function for the OPNQRYF command. For example, you can specify an expression for the QRYSLT parameter without the surrounding delimiters because the system will add the apostrophes. Specify the following:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('CODE *EQ "D" ') PGM(PGMB) OPNID(FILEA) FILE(FILEA)

Notes: 1. The entire expression in the QRYSLT parameter must be enclosed in apostrophes. 2. When specifying eld names in the OPNQRYF command, the names in the record are not enclosed in apostrophes. 3. Character literals must be enclosed by quotation marks or two apostrophes. (The quotation mark character is used in the examples.) It is important to place the character(s) between the quotation marks in either uppercase or lowercase to match the value you want to nd in the database. (The examples are all shown in uppercase.) 4. To request a selection against a numeric constant, specify:
Chapter 6. Opening a Database File

127

OPNQRYF

FILE(FILEA) QRYSLT('AMT *GT 1000.00')

Notice that numeric constants are not enclosed by two apostrophes (quotation marks). 5. When comparing a eld value to a CL variable, use apostrophes as follows (only character CL variables can be used): v If doing selection against a character, date, time, or timestamp eld, specify:
OPNQRYF FILE(FILEA) QRYSLT('"' *CAT &CHAR *CAT '" *EQ FIELDA')

or, in reverse order:

OPNQRYF FILE(FILEA) QRYSLT('FIELDA *EQ "' *CAT &CHAR *CAT '"')

Notice that apostrophes and quotation marks enclose the CL variables and *CAT operators. v If doing selection against a numeric eld, specify:
OPNQRYF FILE(FILEA) QRYSLT(&CHARNUM *CAT ' *EQ NUM')

or, in reverse order:

OPNQRYF FILE(FILEA) QRYSLT('NUM *EQ ' *CAT &CHARNUM);

Notice that apostrophes enclose the eld and operator only. When comparing two elds or constants, the data types must be compatible. The following table describes the valid comparisons.
Table 7. Valid Data Type Comparisons for the OPNQRYF Command Any Numeric Character Date1 Time1 Any Numeric Valid Not Valid Not Valid Not Valid Character Not Valid Valid Valid2 Valid2 Date1 Not Valid Valid2 Valid Not Valid 1 Time Not Valid Valid2 Not Valid Valid Timestamp1 Not Valid Valid2 Not Valid Not Valid :
1

Timestamp1 Not Valid Valid2 Not Valid Not Valid Valid

Date, time, and timestamp data types can be represented by elds and expressions, but not constants; however, character constants can represent date, time, or timestamp values. The character eld or constant must represent a valid date value if compared to a date data type, a valid time value if compared to a time data type, or a valid timestamp value if compared to a timestamp data type.

Note: For DBCS information, see Appendix B. Double-Byte Character Set (DBCS) Considerations. The performance of record selection can be greatly enhanced if some le on the system uses the eld being selected in a keyed sequence access path. This allows the system to quickly access only the records that meet the selection values. If no such access path exists, the system must read every record to determine if it meets the selection values. Even if an access path exists on the eld you want to select from, the system may not use the access path. For example, if it is faster for the system to process the data in arrival sequence, it will do so. See the discussion in Performance Considerations on page 162 for more details.

128

OS/400 DB2 for AS/400 Database Programming V4R3

Example 2: Selecting records with a specic date value Assume you want to process all records in which the Date eld in the record is the same as the current date. Also assume the Date eld is in the same format as the system date. In a CL program, you can specify:
DCL VAR(&CURDAT); TYPE(*CHAR) LEN(6) RTVSYSVAL SYSVAL(QDATE) RTNVAR(&CURDAT); OVRDBF FILE(FILEA) SHARE(*YES) OPNQRYF FILE(FILEA) QRYSLT('"' *CAT &CURDAT *CAT '" *EQ DATE') CALL PGM(PGMB) CLOF OPNID(FILEA) DLTOVR FILE(FILEA)

A CL variable is assigned with a leading ampersand (&); and is not enclosed in apostrophes. The whole expression is enclosed in apostrophes. The CAT operators and CL variable are enclosed in both apostrophes and quotes. It is important to know whether the data in the database is dened as character, date, time, timestamp, or numeric. In the preceding example, the Date eld is assumed to be character. If the DATE eld is dened as date data type, the preceding example could be specied as:
OVRDBF FILE(FILEA) SHARE(*YES) OPNQRYF FILE(FILEA) QRYSLT('%CURDATE *EQ DATE') CALL PGM(PGMB) CLOF OPENID(FILEA) DLTOVR FILE(FILEA)

Note: The date eld does not have to have the same format as the system date. You could also specify the example as:
DCL VAR(&CVTDAT); TYPE(*CHAR) LEN(6) DCL VAR(&CURDAT); TYPE(*CHAR) LEN(8) RTVSYSVAL SYSVAL(QDATE) RTNVAR(&CVTDAT); CVTDAT DATE(&CVTDAT); TOVAR(&CURDAT); TOSEP(/) OVRDBF FILE(FILEA) SHARE(*YES) OPNQRYF FILE(FILEA) QRYSLT('"' *CAT &CURDAT *CAT '" *EQ DATE') CALL PGM(PGMB) CLOF OPNID (FILEA) DLTOVR FILE(FILEA)

This is where DATE has a date data type in FILEA, the job default date format is MMDDYY, and the job default date separator is the slash (/). Note: For any character representation of a date in one of the following formats, MMDDYY, DDMMYY, YYMMDD, or Julian, the job default date format and separator must be the same to be recognized. If, instead, you were using a constant, the QRYSLT would be specied as follows:
QRYSLT('"12/31/87" *EQ DATE')

The job default date format must be MMDDYY and the job default separator must be the slash (/). If a numeric eld exists in the database and you want to compare it to a variable, only a character variable can be used. For example, to select all records where a packed Date eld is greater than a variable, you must ensure the variable is in
Chapter 6. Opening a Database File

129

character form. Normally, this will mean that before the Open Query File (OPNQRYF) command, you use the Change Variable (CHGVAR) command to change the variable from a decimal eld to a character eld. The CHGVAR command would be specied as follows:
CHGVAR VAR(&CHARVAR); VALUE('123188')

The QRYSLT parameter would be specied as follows (see the difference from the preceding examples):
QRYSLT(&CHARVAR *CAT ' *GT DATE')

If, instead, you were using a constant, the QRYSLT statement would be specied as follows:
QRYSLT('123187 *GT DATE')

Example 3: Selecting records in a range of values Assume you have a Date eld specied in the character format YYMMDD and with the . separator, and you want to process all records for 1988. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('DATE *EQ %RANGE("88.01.01" + "88.12.31") ') PGM(PGMC) OPNID(FILEA) FILE(FILEA)

This example would also work if the DATE eld has a date data type, the job default date format is YYMMDD, and the job default date separator is the period (.). Note: For any character representation of a date in one of the following formats, MMDDYY, DDMMYY, YYMMDD, or Julian, the job default date format and separator must be the same to be recognized. If the ranges are variables dened as character data types, and the DATE eld is dened as a character data type, specify the QRYSLT parameter as follows:
QRYSLT('DATE *EQ %RANGE("' *CAT &LORNG *CAT '"' *BCAT '"' *CAT &HIRNG *CAT '")') +

However, if the DATE eld is dened as a numeric data type, specify the QRYSLT parameter as follows:
QRYSLT('DATE *EQ %RANGE(' *CAT &LORNG *BCAT &HIRNG *CAT ')')

Note: *BCAT can be used if the QRYSLT parameter is in a CL program, but it is not allowed in an interactive command. Example 4: Selecting records using the contains function Assume you want to process all records in which the Addr eld contains the street named BROADWAY. The contains (*CT) function determines if the characters appear anywhere in the named eld. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('ADDR *CT "BROADWAY" ') PGM(PGMC) OPNID(FILEA) FILE(FILEA)

130

OS/400 DB2 for AS/400 Database Programming V4R3

In this example, assume that the data is in uppercase in the database record. If the data was in lowercase or mixed case, you could specify a translation function to translate the lowercase or mixed case data to uppercase before the comparison is made. The system-provided table QSYSTRNTBL translates the letters a through z to uppercase. (You could use any translation table to perform the translation.) Therefore, you can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('%XLATE(ADDR QSYSTRNTBL) *CT + "BROADWAY" ') PGM(PGMC) OPNID(FILEA) FILE(FILEA)

When the %XLATE function is used on the QRYSLT statement, the value of the eld passed to the high-level language program appears as it is in the database. You can force the eld to appear in uppercase using the %XLATE function on the MAPFLD parameter. Example 5: Selecting records using multiple elds Assume you want to process all records in which either the Amt eld is equal to zero, or the Lstdat eld (YYMMDD order in character format) is equal to or less than 88-12-31. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('AMT *EQ 0 *OR LSTDAT + *LE "88-12-31" ') PGM(PGMC) OPNID(FILEA) FILE(FILEA)

This example would also work if the LSTDAT eld has a date data type. The LSTDAT eld may be in any valid date format; however, the job default date format must be YYMMDD and the job default date separator must be the dash (). Note: For any character representation of a date in one of the following formats, MMDDYY, DDMMYY, YYMMDD, or Julian, the job default date format and separator must be the same to be recognized. If variables are used, the QRYSLT parameter is typed as follows:
QRYSLT('AMT *EQ ' *CAT &VARAMT *CAT ' *OR + LSTDAT *LE "' *CAT &VARDAT *CAT '"')

or, typed in reverse order:

QRYSLT('"' *CAT &VARDAT *CAT '" *GT LSTDAT *OR ' + *CAT &VARAMT *CAT ' *EQ AMT')

Note that the &VARAMT variable must be dened as a character type. If the variable is passed to your CL program as a numeric type, you must convert it to a character type to allow concatenation. You can use the Change Variable (CHGVAR) command to do this conversion. Example 6: Using the Open Query File (OPNQRYF) command many times in a program You can use the OPNQRYF command more than once in a high-level language program. For example, assume you want to prompt the user for some selection values, then display one or more pages of records. At the end of the rst request
Chapter 6. Opening a Database File

131

for records, the user may want to specify other selection values and display those records. This can be done by doing the following: 1. Before calling the high-level language program, use an Override with Database File (OVRDBF) command to specify SHARE(*YES). 2. In the high-level language program, prompt the user for the selection values. 3. Pass the selection values to a CL program that issues the OPNQRYF command (or run the command with a call to program QCMDEXC). The le must be closed before your program processes the OPNQRYF command. You normally use the Close File (CLOF) command and monitor for the le not being open. 4. Return to the high-level language program. 5. 6. 7. 8. Open the le in the high-level language program. Process the records. Close the le in the program. Return to step 2.

When the program completes, run the Close File (CLOF) command or the Reclaim Resources (RCLRSC) command to close the le, then delete the Override with Database File command specied in step 1. Note: An override command in a called CL program does not affect the open in the main program. All overrides are implicitly deleted when the program is ended. (However, you can use a call to program QCMDEXC from your high-level language program to specify an override, if needed.) Example 7: Mapping elds for packed numeric data elds Assume you have a packed decimal Date eld in the format MMDDYY and you want to select all the records for the year 1988. You cannot select records directly from a portion of a packed decimal eld, but you can use the MAPFLD parameter on the OPNQRYF command to create a new eld that you can then use for selecting part of the eld. The format of each mapped eld denition is: (result eld expression attributes) where:
result eld expression = = The name of the result eld. How the result eld should be derived. The expression can include substring, other built-in functions, or mathematical statements. The optional attributes of the result eld. If no attributes are given (or the eld is not dened in a le), the OPNQRYF command calculates a eld attribute determined by the elds in the expression.

attributes

132

OS/400 DB2 for AS/400 Database Programming V4R3

OVRDBF OPNQRYF CALL CLOF DLTOVR

FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('YEAR *EQ "88" ') + MAPFLD((CHAR6 '%DIGITS(DATE)') + (YEAR '%SST(CHAR6 5 2)' *CHAR 2)) PGM(PGMC) OPNID(FILEA) FILE(FILEA)

In this example, if DATE was a date data type, it could be specied as follows:
OPNQRYF FILE(FILEA) + QRYSLT ('YEAR *EQ 88') + MAPFLD((YEAR '%YEAR(DATE)'))

The rst mapped eld denition species that the Char6 eld be created from the packed decimal Date eld. The %DIGITS function converts from packed decimal to character and ignores any decimal denitions (that is, 1234.56 is converted to 123456). Because no denition of the Char6 eld is specied, the system assigns a length of 6. The second mapped eld denes the Year eld as type *CHAR (character) and length 2. The expression uses the substring function to map the last 2 characters of the Char6 eld into the Year eld. Note that the mapped eld denitions are processed in the order in which they are specied. In this example, the Date eld was converted to character and assigned to the Char6 eld. Then, the last two digits of the Char6 eld (the year) were assigned to the Year eld. Any changes to this order would have produced an incorrect result. Note: Mapped eld denitions are always processed before the QRYSLT parameter is evaluated. You could accomplish the same result by specifying the substring on the QRYSLT parameter and dropping one of the mapped eld denitions as follows:
OPNQRYF FILE(FILEA) + QRYSLT('%SST(CHAR6 5 2) *EQ "88" ') + MAPFLD((CHAR6 '%DIGITS(DATE)'))

Example 8: Using the wildcard function Assume you have a packed decimal Date eld in the format MMDDYY and you want to select the records for March 1988. To do this, you can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) + QRYSLT('%DIGITS(DATE) *EQ %WLDCRD("03__88")') PGM(PGMC) OPNID(FILEA) FILE(FILEA)

Note that the only time the MAPFLD parameter is needed to dene a database eld for the result of the %DIGITS function is when the result needs to be used with a function that only supports a simple eld name (not a function or expression) as an argument. The %WLDCRD operation has no such restriction on the operand that appears before the *EQ operator. Note that although the eld in the database is in numeric form, double apostrophes surround the literal to make its denition the same as the Char6 eld. The wildcard function is not supported for DATE, TIME, or TIMESTAMP data types.

Chapter 6. Opening a Database File

133

The %WLDCRD function lets you select any records that match your selection values, in which the underline (_) will match any single character value. The two underline characters in Example 8 allow any day in the month of March to be selected. The %WLDCRD function also allows you to name the wild card character (underline is the default). The wild card function supports two different forms: v A xed-position wild card as shown in the previous example in which the underline (or your designated character) matches any single character as in the following example:
QRYSLT('FLDA *EQ %WLDCRD("A_C")')

This compares successfully to ABC, ACC, ADC, AxC, and so on. In this example, the eld being analyzed only compares correctly if it is exactly 3 characters in length. If the eld is longer than 3 characters, you also need the second form of wild card support. v A variable-position wild card will match any zero or more characters. The Open Query File (OPNQRYF) command uses an asterisk (*) for this type of wild card variable character or you can specify your own character. An asterisk is used in the following example:
QRYSLT('FLDB *EQ %WLDCRD("A*C*") ')

This compares successfully to AC, ABC, AxC, ABCD, AxxxxxxxC, and so on. The asterisk causes the command to ignore any intervening characters if they exist. Notice that in this example the asterisk is specied both before and after the character or characters that can appear later in the eld. If the asterisk were omitted from the end of the search argument, it causes a selection only if the eld ends with the character C. You must specify an asterisk at the start of the wild card string if you want to select records where the remainder of the pattern starts anywhere in the eld. Similarly, the pattern string must end with an asterisk if you want to select records where the remainder of the pattern ends anywhere in the eld. For example, you can specify:
QRYSLT('FLDB *EQ %WLDCRD("*ABC*DEF*") ')

You get a match on ABCDEF, ABCxDEF, ABCxDEFx, ABCxxxxxxDEF, ABCxxxDEFxxx, xABCDEF, xABCxDEFx, and so on. You can combine the two wildcard functions as in the following example:
QRYSLT('FLDB *EQ %WLDCRD("ABC_*DEF*") ')

You get a match on ABCxDEF, ABCxxxxxxDEF, ABCxxxDEFxxx, and so on. The underline forces at least one character to appear between the ABC and DEF (for example, ABCDEF would not match). Assume you have a Name eld that contains: JOHNS JOHNS SMITH JOHNSON JOHNSTON If you specify the following you will only get the rst record:

134

OS/400 DB2 for AS/400 Database Programming V4R3

QRYSLT('NAME *EQ "JOHNS"')

You would not select the other records because a comparison is made with blanks added to the value you specied. The way to select all four names is to specify:
QRYSLT('NAME *EQ %WLDCRD("JOHNS*")')

Note: For information about using the %WLDCRD function for DBCS, see Appendix B. Double-Byte Character Set (DBCS) Considerations. Example 9: Using complex selection statements Complex selection statements can also be specied. For example, you can specify:
QRYSLT('DATE *EQ "880101" *AND AMT *GT 5000.00') QRYSLT('DATE *EQ "880101" *OR AMT *GT 5000.00')

You can also specify:

QRYSLT('CODE *EQ "A" *AND TYPE *EQ "X" *OR CODE *EQ "B")

The rules governing the priority of processing the operators are described in the CL Reference (Abridged) manual. Some of the rules are: v The *AND operations are processed rst; therefore, the record would be selected if: The Code eld = "A" and The Type eld = "X" or The Code eld = "B" v Parentheses can be used to control how the expression is handled, as in the following example:
QRYSLT('(CODE *EQ "A" *OR CODE *EQ "B") *AND TYPE *EQ "X" + *OR CODE *EQ "C"')

The Code eld = "A" or The Code eld = "B" or The Code eld = "C"

and and

The Type eld= "X" The Type eld = "X"

You can also use the symbols described in the CL Reference (Abridged) manual instead of the abbreviated form (for example, you can use = instead of *EQ) as in the following example:
QRYSLT('CODE = "A" & TYPE = "X" | AMT > 5000.00')

This command selects all records in which: The Code eld = "A" and or The Amt eld > 5000.00 The Type eld = "X"

A complex selection statement can also be written, as in the following example:

QRYSLT('CUSNBR = %RANGE("60000" "69999") & TYPE = "B" + & SALES>0 & ACCRCV / SALES>.3')

This command selects all records in which:

Chapter 6. Opening a Database File

135

The Cusnbr eld is in the range 60000-69999 and The Type eld = "B" and The Sales elds are greater than 0 and Accrcv divided by Sales is greater than 30 percent Example 10: Using coded character set identiers (CCSIDs) For general information about CCSIDs, see the National Language Support book. Each character and DBCS eld in all database les is tagged with a CCSID. This CCSID allows you to further dene the data stored in the le so that any comparison, join, or display of the elds is performed in a meaningful way. For example, if you compared FIELD1 in FILE1 where FIELD1 has a CCSID of 37 (USA) to FIELD2 in FILE2 where FILED2 has a CCSID of 273 (Austria, Germany) appropriate mapping would occur to make the comparison meaningful.
OPNQRYF FILE(FILEA FILEB) FORMAT(RESULTF) + JFLD((FILEA/NAME FILEB/CUSTOMER))

If eld NAME has a CCSID of 37 and eld CUSTOMER has a CCSID of 273, the mapping of either NAME or CUSTOMER is performed during processing of the OPNQRYF command so that the join of the two elds provides a meaningful result. Normally, constants dened in the MAPFLD, QRYSLT, and GRPSLT parameters are tagged with the CCSID dened to the current job. This suggests that when two users with different job CCSIDs run the same OPNQRYF command (or a program containing an OPNQRYF command) and the OPNQRYF has constants dened in it, the users can get different results because the CCSID tagged to the constants may cause the constants to be treated differently. You can tag a constant with a specic CCSID by using the MAPFLD parameter. By specifying a MAPFLD whose denition consists solely of a constant and then specifying a CCSID for the MAPFLD the constant becomes tagged with the CCSID specied in the MAPFLD parameter. For example:
OPNQRYF FILE(FILEA) FORMAT(RESULTF) QRYSLT('NAME *EQ MAP1') + MAPFLD((MAP1 '"Smith"' *CHAR 5 *N 37))

The constant Smith is tagged with the CCSID 37 regardless of the job CCSID of the user issuing the OPNQRYF command. In this example, all users would get the same result records (although the result records would be mapped to the users job CCSID). Conversely, if the query is specied as:
OPNQRYF FILE(FILEA) FORMAT(RESULTF) QRYSLT('NAME *EQ "Smith"')

the results of the query may differ, depending on the job CCSID of the user issuing the OPNQRYF command. Example 11: Using Sort Sequence and Language Identier To see how to use a sort sequence, run the examples in this section against the STAFF le shown in Table 8.
Table 8. The STAFF File ID 10 20 NAME Sanders Pernal DEPT 20 20 JOB Mgr Sales YEARS 7 8 SALARY 18357.50 18171.25 COMM 0 612.45

136

OS/400 DB2 for AS/400 Database Programming V4R3

Table 8. The STAFF File (continued) ID 30 40 50 60 70 80 90 100 NAME Merenghi OBrien Hanes Quigley Rothman James Koonitz Plotz DEPT 38 38 15 38 15 20 42 42 JOB MGR Sales Mgr SALES Sales Clerk sales mgr YEARS 5 6 10 00 7 0 6 6 SALARY 17506.75 18006.00 20659.80 16808.30 16502.83 13504.60 18001.75 18352.80 COMM 0 846.55 0 650.25 1152.00 128.20 1386.70 0

In the examples, the results are shown for a particular statement using each of the following: v *HEX sort sequence. v Shared-weight sort sequence for language identier ENU. v Unique-weight sort sequence for language identier ENU. Note: ENU is chosen as a language identier by specifying either SRTSEQ(*LANGIDUNQ) or SRTSEQ(*LANGIDSHR), and LANGID(ENU) in the OPNQRYF command. The following command selects records with the value MGR in the JOB eld:
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"')

Table 9 shows the record selection with the *HEX sort sequence. The records that match the record selection criteria for the JOB eld are selected exactly as specied in the QRYSLT statement; only the uppercase MGR is selected.
Table 9. Using the *HEX Sort Sequence. OPNQRYF FILE(STAFF) QRYSLT(JOB *EQ MGR) SRTSEQ(*HEX) ID 30 NAME Merenghi DEPT 38 JOB MGR YEARS 5 SALARY 17506.75 COMM 0

Table 10 shows the record selection with the shared-weight sort sequence. The records that match the record selection criteria for the JOB eld are selected by treating uppercase and lowercase letters the same. With this sort sequence, mgr, Mgr, and MGR values are selected.
Table 10. Using the Shared-Weight Sort Sequence. OPNQRYF FILE(STAFF) QRYSLT(JOB *EQ MGR) SRTSEQ(LANGIDSHR) LANGID(ENU) ID 10 30 50 100 NAME Sanders Merenghi Hanes Plotz DEPT 20 38 15 42 JOB Mgr MGR Mgr mgr YEARS 7 5 10 6 SALARY 18357.50 17506.75 20659.80 18352.80 COMM 0 0 0 0

Table 11 on page 138 shows the record selection with the unique-weight sort sequence. The records that match the record selection criteria for the JOB eld are selected by treating uppercase and lowercase letters as unique. With this sort
Chapter 6. Opening a Database File

137

sequence, the mgr, Mgr, and MGR values are all different. The MGR value is selected.
Table 11. Using the Unique-Weight Sort Sequence. OPNQRYF FILE(STAFF) QRYSLT(JOB *EQ MGR) SRTSEQ(LANGIDUNQ) LANGID(ENU) ID 30 NAME Merenghi DEPT 38 JOB MGR YEARS 5 SALARY 17506.75 COMM 0

Specifying a Keyed Sequence Access Path without Using DDS

The dynamic access path function allows you to specify a keyed access path for the data to be processed. If an access path already exists that can be shared, the system can share it. If a new access path is required, it is built before any records are passed to the program. Example 1: Arranging records using one key eld Assume you want to process the records in FILEA arranged by the value in the Cust eld with program PGMD. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) KEYFLD(CUST) PGM(PGMD) OPNID(FILEA) FILE(FILEA)

Note: The FORMAT parameter on the Open Query File (OPNQRYF) command is not needed because PGMD is created by specifying FILEA as the processed le. FILEA can be an arrival sequence or a keyed sequence le. If FILEA is keyed, its key eld can be the Cust eld or a totally different eld. Example 2: Arranging records using multiple key elds If you want the records to be processed by Cust sequence and then by Date in Cust, specify:
OPNQRYF FILE(FILEA) KEYFLD(CUST DATE)

If you want the Date to appear in descending sequence, specify:

OPNQRYF FILE(FILEA) KEYFLD((CUST) (DATE *DESCEND))

In these two examples, the FORMAT parameter is not used. (If a different format is dened, all key elds must exist in the format.) Example 3: Arranging records using a unique-weight sort sequence. To process the records by the JOB eld values with a unique-weight sort sequence using the STAFF le in Table 8 on page 136, specify:
OPNQRYF FILE(STAFF) KEYFLD(JOB) SRTSEQ(*LANGIDUNQ) LANGID(ENU)

This query results in a JOB eld in the following sequence: Clerk mgr Mgr Mgr MGR sales

138

OS/400 DB2 for AS/400 Database Programming V4R3

Sales Sales Sales SALES Example 4: Arranging records using a shared-weight sort sequence. To process the records by the JOB eld values with a unique-weight sort sequence using the STAFF le in Table 8 on page 136, specify:
OPNQRYF FILE(STAFF) KEYFLD(JOB) SRTSEQ(*LANGIDSHR) LANGID(ENU)

The results from this query will be similar to the results in Example 3. The mgr and sales entries could be in any sequence because the uppercase and lowercase letters are treated as equals. That is, the shared-weight sort sequence treats mgr, Mgr, and MGR as equal values. Likewise, sales, Sales, and SALES are treated as equal values.

Specifying Key Fields from Different Files

A dynamic keyed sequence access path over a join logical le allows you to specify a processing sequence in which the keys can be in different physical les (DDS restricts the keys to the primary le). The specication is identical to the previous method. The access path is specied using whatever key elds are required. There is no restriction on which physical le the key elds are in. However, if a key eld exists in other than the primary le of a join specication, the system must make a temporary copy of the joined records. The system must also build a keyed sequence access path over the copied records before the query le is opened. The key elds must exist in the format identied on the FORMAT parameter. Example 1: Using a eld in a secondary le as a key eld Assume you already have a join logical le named JOINLF. FILEX is specied as the primary le and is joined to FILEY. You want to process the records in JOINLF by the Descrp eld which is in FILEY. Assume the le record formats contain the following elds:
FILEX Item Qty FILEY Item Descrp JOINLF Item Qty Descrp

You can specify:

OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(JOINLF) SHARE(*YES) FILE(JOINLF) KEYFLD(DESCRP) PGM(PGMC) OPNID(JOINLF) FILE(JOINLF)

If you want to arrange the records by Qty in Descrp (Descrp is the primary key eld and Qty is a secondary key eld) you can specify:
OPNQRYF FILE(JOINLF) KEYFLD(DESCRP QTY)

Chapter 6. Opening a Database File

139

Dynamically Joining Database Files without DDS

The dynamic join function allows you to join les without having to rst specify DDS and create a join logical le. You must use the FORMAT parameter on the Open Query File (OPNQRYF) command to specify the record format for the join. You can join any physical or logical le including a join logical le and a view (DDS does not allow you to join logical les). You can specify either a keyed or arrival sequence access path. If keys are specied, they can be from any of the les included in the join (DDS restricts keys to just the primary le). In the following examples, it is assumed that the le specied on the FORMAT parameter was created. You will normally want to create the le before you create the processing program so you can use the externally described data denitions. The default for the join order (JORDER) parameter is used in all of the following examples. The default for the JORDER parameter is *ANY, which tells the system that it can determine the order in which to join the les. That is, the system determines which le to use as the primary le and which as the secondary les. This allows the system to try to improve the performance of the join function. The join criterion, like the record selection criterion, is affected by the sort sequence (SRTSEQ) and the language identier (LANGID) specied (see Example 11 on page 136 ). Example 1: Dynamically joining les Assume you want to join FILEA and FILEB. Assume the les contain the following elds:
FILEA Cust Name Addr FILEB Cust Amt JOINAB Cust Name Amt

The join eld is Cust which exists in both les. Any record format name can be specied in the Open Query File (OPNQRYF) command for the join le. The le does not need a member. The records are not required to be in keyed sequence. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(JOINAB) TOFILE(FILEA) SHARE(*YES) FILE(FILEA FILEB) FORMAT(JOINAB) + JFLD((FILEA/CUST FILEB/CUST)) + MAPFLD((CUST 'FILEA/CUST')) PGM(PGME) /* Created using file JOINAB as input */ OPNID(FILEA) FILE(JOINAB)

File JOINAB is a physical le with no data. This is the le that contains the record format to be specied on the FORMAT parameter in the Open Query File (OPNQRYF) command. Notice that the TOFILE parameter on the Override with Database File (OVRDBF) command species the name of the primary le for the join operation (the rst le specied for the FILE parameter on the OPNQRYF command). In this example, the FILE parameter on the Open Query File (OPNQRYF) command identies the les in the sequence they are to be joined (A to B). The format for the le is in the le JOINAB.

140

OS/400 DB2 for AS/400 Database Programming V4R3

The JFLD parameter identies the Cust eld in FILEA to join to the Cust eld in FILEB. Because the Cust eld is not unique across all of the joined record formats, it must be qualied on the JFLD parameter. The system attempts to determine, in some cases, the most efficient values even if you do not specify the JFLD parameter on the Open Query File (OPNQRYF) command. For example, using the previous example, if you specied:
OPNQRYF FILE(FILEA FILEB) FORMAT(JOINAB) + QRYSLT('FILEA/CUST *EQ FILEB/CUST') + MAPFLD((CUST 'FILEA/CUST'))

The system joins FILEA and FILEB using the Cust eld because of the values specied for the QRYSLT parameter. Notice that in this example the JFLD parameter is not specied on the command. However, if either JDFTVAL(*ONLYDFT) or JDFTVAL(*YES) is specied on the OPNQRYF command, the JFLD parameter must be specied. The MAPFLD parameter is needed on the Open Query File (OPNQRYF) command to describe which le should be used for the data for the Cust eld in the record format for le JOINAB. If a eld is dened on the MAPFLD parameter, its unqualied name (the Cust eld in this case without the le name identication) can be used anywhere else in the OPNQRYF command. Because the Cust eld is dened on the MAPFLD parameter, the rst value of the JFLD parameter need not be qualied. For example, the same result could be achieved by specifying:
JFLD((CUST FILEB/CUST)) + MAPFLD((CUST 'FILEA/CUST'))

Any other uses of the same eld name in the Open Query File (OPNQRYF) command to indicate a eld from a le other than the le dened by the MAPFLD parameter must be qualied with a le name. Because no KEYFLD parameter is specied, the records appear in any sequence depending on how the Open Query File (OPNQRYF) command selects the records. You can force the system to arrange the records the same as the primary le. To do this, specify *FILE on the KEYFLD parameter. You can specify this even if the primary le is in arrival sequence. The JDFTVAL parameter (similar to the JDFTVAL keyword in DDS) can also be specied on the Open Query File (OPNQRYF) command to describe what the system should do if one of the records is missing from the secondary le. In this example, the JDFTVAL parameter was not specied, so only the records that exist in both les are selected. If you tell the system to improve the results of the query (through parameters on the OPNQRYF command), it will generally try to use the le with the smallest number of records selected as the primary le. However, the system will also try to avoid building a temporary le. You can force the system to follow the le sequence of the join as you have specied it in the FILE parameter on the Open Query File (OPNQRYF) command by specifying JORDER(*FILE). If JDFTVAL(*YES) or JDFTVAL(*ONLYDFT) is specied, the system will never change the join le sequence because a different sequence could cause different results. Example 2: Reading only those records with secondary le records

Chapter 6. Opening a Database File

141

Assume you want to join les FILEAB, FILECD, and FILEEF to select only those records with matching records in secondary les. Dene a le JOINF and describe the format that should be used. Assume the record formats for the les contain the following elds:
FILEAB Abitm Abord Abdat FILECD Cditm Cddscp Cdcolr FILEEF Etm Efcolr Efqty JOINF Abitm Abord Cddscp Cdcolr Efqty

In this case, all eld names in the les that make up the join le begin with a 2-character prex (identical for all elds in the le) and end with a suffix that is identical across all the les (for example, xxitm). This makes all eld names unique and avoids having to qualify them. The xxitm eld allows the join from FILEAB to FILECD. The two elds xxitm and xxcolr allow the join from FILECD to FILEEF. A keyed sequence access path does not have to exist for these les. However, if a keyed sequence access path does exist, performance may improve signicantly because the system will attempt to use the existing access path to arrange and select records, where it can. If access paths do not exist, the system automatically creates and maintains them as long as the le is open.
OVRDBF OPNQRYF FILE(JOINF) TOFILE(FILEAB) SHARE(*YES) FILE(FILEAB FILECD FILEEF) + FORMAT(JOINF) + JFLD((ABITM CDITM)(CDITM EFITM) + (CDCOLR EFCOLR)) PGM(PGME) /* Created using file JOINF as input */ OPNID(FILEAB) FILE(JOINF)

CALL CLOF DLTOVR

The join eld pairs do not have to be specied in the order shown above. For example, the same result is achieved with a JFLD parameter value of:
JFLD((CDCOLR EFCOLR)(ABITM CDITM) (CDITM EFITM))

The attributes of each pair of join elds do not have to be identical. Normal padding of character elds and decimal alignment for numeric elds occurs automatically. The JDFTVAL parameter is not specied so *NO is assumed and no default values are used to construct join records. If you specied JDFTVAL(*YES) and there is no record in le FILECD that has the same join eld value as a record in le FILEAB, defaults are used for the Cddscp and Cdcolr elds to join to le FILEEF. Using these defaults, a matching record can be found in le FILEEF (depending on if the default value matches a record in the secondary le). If not, a default value appears for these les and for the Efqty eld. Example 3: Using mapped elds as join elds You can use elds dened on the MAPFLD parameter for either one of the join eld pairs. This is useful when the key in the secondary le is dened as a single eld (for example, a 6-character date eld) and there are separate elds for the same information (for example, month, day, and year) in the primary le. Assume FILEA has character elds Year, Month, and Day and needs to be joined to FILEB

142

OS/400 DB2 for AS/400 Database Programming V4R3

which has the Date eld in YYMMDD format. Assume you have dened le JOINAB with the desired format. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(JOINAB) TOFILE(FILEA) SHARE(*YES) FILE(FILEA FILEB) FORMAT(JOINAB) + JFLD((YYMMDD FILEB/DATE)) + MAPFLD((YYMMDD 'YEAR *CAT MONTH *CAT DAY')) PGM(PGME) /* Created using file JOINAB as input */ OPNID(FILEA) FILE(JOINAB)

The MAPFLD parameter denes the YYMMDD eld as the concatenation of several elds from FILEA. You do not need to specify eld attributes (for example, length or type) for the YYMMDD eld on the MAPFLD parameter because the system calculates the attributes from the expression.

Handling Missing Records in Secondary Join Files

The system allows you to control whether to allow defaults for missing records in secondary les (similar to the JDFTVAL DDS keyword for a join logical le). You can also specify that only records with defaults be processed. This allows you to select only those records in which there is a missing record in the secondary le. Example 1: Reading records from the primary le that do not have a record in the secondary le In Example 1 under Dynamically Joining Database Files without DDS on page 140 , the JDFTVAL parameter is not specied, so the only records read are the result of a successful join from FILEA to FILEB. If you want a list of the records in FILEA that do not have a match in FILEB, you can specify *ONLYDFT on the JDFTVAL parameter as shown in the following example:
OVRDBF OPNQRYF FILE(FILEA) SHARE(*YES) FILE(FILEA FILEB) FORMAT(FILEA) + JFLD((CUST FILEB/CUST)) + MAPFLD((CUST 'FILEA/CUST')) + JDFTVAL(*ONLYDFT) PGM(PGME) /* Created using file FILEA as input */ OPNID(FILEA) FILE(FILEA)

CALL CLOF DLTOVR

JDFTVAL(*ONLYDFT) causes a record to be returned to the program only when there is no equivalent record in the secondary le (FILEB). Because any values returned by the join operation for the elds in FILEB are defaults, it is normal to use only the format for FILEA. The records that appear are those that do not have a match in FILEB. The FORMAT parameter is required whenever the FILE parameter describes more than a single le, but the le name specied can be one of the les specied on the FILE parameter. The program is created using FILEA. Conversely, you can also get a list of all the records where there is a record in FILEB that does not have a match in FILEA. You can do this by making the secondary le the primary le in all the specications. You would specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEB) SHARE(*YES) FILE(FILEB FILEA) FORMAT(FILEB) JFLD((CUST FILEA/CUST)) + MAPFLD((CUST 'FILEB/CUST')) JDFTVAL(*ONLYDFT) PGM(PGMF) /* Created using file FILEB as input */ OPNID(FILEB) FILE(FILEB)
Chapter 6. Opening a Database File

143

Note: The Override with Database File (OVRDBF) command in this example uses FILE(FILEB) because it must specify the rst le on the OPNQRYF FILE parameter. The Close File (CLOF) command also names FILEB. The JFLD and MAPFLD parameters also changed. The program is created using FILEB.

Unique-Key Processing
Unique-key processing allows you to process only the rst record of a group. The group is dened by one or more records with the same set of key values. Processing the rst record implies that the records you receive will have unique keys. When you use unique-key processing, you can only read the le sequentially. The key elds are sorted according to the specied sort sequence (SRTSEQ) and language identier (LANGID) (see Example 3 on page 138 and Example 4 on page 139 ). Example 1: Reading only unique-key records Assume you want to process FILEA, which has records with duplicate keys for the Cust eld. You want only the rst record for each unique value of the Cust eld to be processed by program PGMF. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) KEYFLD(CUST) UNIQUEKEY(*ALL) PGM(PGMF) OPNID(FILEA) FILE(FILEA)

Example 2: Reading records using only some of the key elds Assume you want to process the same le with the sequence: Slsman, Cust, Date, but you want only one record per Slsman and Cust. Assume the records in the le are:
Slsman 01 01 01 01 02 Cust 5000 5000 4025 4025 3000 Date 880109 880115 880103 880101 880101 Record # 1 2 3 4 5

You specify the number of key elds that are unique, starting with the rst key eld.
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) KEYFLD(SLSMAN CUST DATE) UNIQUEKEY(2) PGM(PGMD) OPNID(FILEA) FILE(FILEA)

The following records are retrieved by the program:

Slsman 01 01 02 Cust 4025 5000 3000 Date 880101 880109 880101 Record # 4 1 5

144

OS/400 DB2 for AS/400 Database Programming V4R3

Note: Null values are treated as equal, so only the rst null value would be returned.

Dening Fields Derived from Existing Field Denitions

Mapped eld denitions: v Allow you to create internal elds that specify selection values (see Example 7 under Selecting Records without Using DDS on page 127 for more information). v Allow you to avoid confusion when the same eld name occurs in multiple les (see Example 1 under Dynamically Joining Database Files without DDS on page 140 for more information). v Allow you to create elds that exist only in the format to be processed, but not in the database itself. This allows you to perform translate, substring, concatenation, and complex mathematical operations. The following examples describe this function. Example 1: Using derived elds Assume you have the Price and Qty elds in the record format. You can multiply one eld by the other by using the Open Query File (OPNQRYF) command to create the derived Exten eld. You want FILEA to be processed, and you have already created FILEAA. Assume the record formats for the les contain the following elds:
FILEA Order Item Qty Price Descrp FILEAA Order Item Exten Brfdsc

The Exten eld is a mapped eld. Its value is determined by multiplying Qty times Price. It is not necessary to have either the Qty or Price eld in the new format, but they can exist in that format, too if you wish. The Brfdsc eld is a brief description of the Descrp eld (it uses the rst 10 characters). Assume you have specied PGMF to process the new format. To create this program, use FILEAA as the le to read. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEAA) TOFILE(FILEA) SHARE(*YES) FILE(FILEA) FORMAT(FILEAA) + MAPFLD((EXTEN 'PRICE * QTY') + (BRFDSC 'DESCRP')) PGM(PGMF) /* Created using file FILEAA as input */ OPNID(FILEA) FILE(FILEAA)

Notice that the attributes of the Exten eld are those dened in the record format for FILEAA. If the value calculated for the eld is too large, an exception is sent to the program. It is not necessary to use the substring function to map to the Brfdsc eld if you only want the characters from the beginning of the eld. The length of the Brfdsc eld is dened in the FILEAA record format.

Chapter 6. Opening a Database File

145

All elds in the format specied on the FORMAT parameter must be described on the OPNQRYF command. That is, all elds in the output format must either exist in one of the record formats for the les specied on the FILE parameter or be dened on the MAPFLD parameter. If you have elds in the format on the FORMAT parameter that your program does not use, you can use the MAPFLD parameter to place zeros or blanks in the elds. Assume the Fldc eld is a character eld and the Fldn eld is a numeric eld in the output format, and you are using neither value in your program. You can avoid an error on the OPNQRYF command by specifying:
MAPFLD((FLDC ' " " ')(FLDN 0))

Notice quotation marks enclose a blank value. By using a constant for the denition of an unused eld, you avoid having to create a unique format for each use of the OPNQRYF command. Example 2: Using built-in functions Assume you want to calculate a mathematical function that is the sine of the Fldm eld in FILEA. First create a le (assume it is called FILEAA) with a record format containing the following elds:
FILEA Code Fldm FILEAA Code Fldm Sinm

You can then create a program (assume PGMF) using FILEAA as input and specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEAA) TOFILE(FILEA) SHARE(*YES) FILE(FILEA) FORMAT(FILEAA) + MAPFLD((SINM '%SIN(FLDM)')) PGM(PGMF) /* Created using file FILEAA as input */ OPNID(FILEA) FILE(FILEAA)

The built-in function %SIN calculates the sine of the eld specied as its argument. Because the Sinm eld is dened in the format specied on the FORMAT parameter, the OPNQRYF command converts its internal denition of the sine value (in oating point) to the denition of the Sinm eld. This technique can be used to avoid certain high-level language restrictions regarding the use of oating-point elds. For example, if you dened the Sinm eld as a packed decimal eld, PGMF could be written using any high-level language, even though the value was built using a oating-point eld. There are many other functions besides sine that can be used. Refer to the OPNQRYF command in the CL Reference (Abridged) manual for a complete list of built-in functions. Example 3: Using derived elds and built-in functions Assume, in the previous example, that a eld called Fldx also exists in FILEA, and the Fldx eld has appropriate attributes used to hold the sine of the Fldm eld. Also assume that you are not using the contents of the Fldx eld. You can use the MAPFLD parameter to change the contents of a eld before passing it to your high-level language program. For example, you can specify:

146

OS/400 DB2 for AS/400 Database Programming V4R3

OVRDBF OPNQRYF CALL CLOF DLTOVR

FILE(FILEA) SHARE(*YES) FILE(FILEA) MAPFLD((FLDX '%SIN(FLDM)')) PGM(PGMF) /* Created using file FILEA as input */ OPNID(FILEA) FILE(FILEA)

In this case, you do not need to specify a different record format on the FORMAT parameter. (The default uses the format of the rst le on the FILE parameter.) Therefore, the program is created by using FILEA. When using this technique, you must ensure that the eld you redene has attributes that allow the calculated value to process correctly. The least complicated approach is to create a separate le with the specic elds you want to process for each query. You can also use this technique with a mapped eld denition and the %XLATE function to translate a eld so that it appears to the program in a different manner than what exists in the database. For example, you can translate a lowercase eld so the program only sees uppercase. The sort sequence and language identier can affect the results of the %MIN and %MAX built-in functions. For example, the uppercase and lowercase versions of letters can be equal or unequal depending on the selected sort sequence and language identier. Note that the translated eld value is used to determine the minimum and maximum, but the untranslated value is returned in the result record. The example described uses FILEA as an input le. You can also update data using the OPNQRYF command. However, if you use a mapped eld denition to change a eld, updates to the eld are ignored.

Handling Divide by Zero

Dividing by zero is considered an error by the Open Query File (OPNQRYF) command. Record selection is normally done before eld mapping errors occur (for example, where eld mapping would cause a division error). Therefore, a record can be omitted (based on the QRYSLT parameter values and valid data in the record) that would have caused a divide-by-zero error. In such an instance, the record would be omitted and processing by the OPNQRYF command would continue. If you want a zero answer, the following describes a solution that is practical for typical commercial data. Assume you want to divide A by B giving C (stated as A / B = C). Assume the following denitions where B can be zero.
Field A B C Digits 6 3 6 Dec 2 0 2

The following algorithm can be used:

(A * B) / %MAX((B * B) .nnnn1)

The %MAX function returns the maximum value of either B * B or a small value. The small value must have enough leading zeros so that it is less than any value calculated by B * B unless B is zero. In this example, B has zero decimal positions
Chapter 6. Opening a Database File

147

so .1 could be used. The number of leading zeros should be 2 times the number of decimals in B. For example, if B had 2 decimal positions, then .00001 should be used. Specify the following MAPFLD denition:
MAPFLD((C '(A * B) / %MAX((B * B) .1)'))

The intent of the rst multiplication is to produce a zero dividend if B is zero. This will ensure a zero result when the division occurs. Dividing by zero does not occur if B is zero because the .1 value will be the value used as the divisor.

Summarizing Data from Database File Records (Grouping)

The group processing function allows you to summarize data from existing database records. You can specify: v The grouping elds v Selection values both before and after grouping v A keyed sequence access path over the new records v Mapped eld denitions that allow you to do such functions as sum, average, standard deviation, and variance, as well as counting the records in each group v The sort sequence and language identier that supply the weights by which the eld values are grouped You normally start by creating a le with a record format containing only the following types of elds: v Grouping elds. Specied on the GRPFLD parameter that dene groups. Each group contains a constant set of values for all grouping elds. The grouping elds do not need to appear in the record format identied on the FORMAT parameter. v Aggregate elds. Dened by using the MAPFLD parameter with one or more of the following built-in functions: %COUNT Counts the records in a group %SUM A sum of the values of a eld over the group %AVG Arithmetic average (mean) of a eld, over the group %MAX Maximum value in the group for the eld %MIN Minimum value in the group for the eld %STDDEV Standard deviation of a eld, over the group %VAR Variance of a eld, over the group v Constant elds. Allow constants to be placed in eld values. The restriction that the Open Query File (OPNQRYF) command must know all elds in the output format is also true for the grouping function. When you use group processing, you can only read the le sequentially. Example 1: Using group processing

148

OS/400 DB2 for AS/400 Database Programming V4R3

Assume you want to group the data by customer number and analyze the amount eld. Your database le is FILEA and you create a le named FILEAA containing a record format with the following elds:
FILEA Cust Type Amt FILEAA Cust Count (count of records per customer) Amtsum (summation of the amount eld) Amtavg (average of the amount eld) Amtmax (maximum value of the amount eld)

When you dene the elds in the new le, you must ensure that they are large enough to hold the results. For example, if the Amt eld is dened as 5 digits, you may want to dene the Amtsum eld as 7 digits. Any arithmetic overow causes your program to end abnormally. Assume the records in FILEA have the following values:
Cust 001 001 004 002 003 001 004 003 Type A B A A B A A B Amt 500.00 700.00 100.00 1200.00 900.00 300.00 300.00 600.00

You then create a program (PGMG) using FILEAA as input to print the records.
OVRDBF OPNQRYF FILE(FILEAA) TOFILE(FILEA) SHARE(*YES) FILE(FILEA) FORMAT(FILEAA) KEYFLD(CUST) + GRPFLD(CUST) MAPFLD((COUNT '%COUNT') + (AMTSUM '%SUM(AMT)') + (AMTAVG '%AVG(AMT)') + (AMTMAX '%MAX(AMT)')) PGM(PGMG) /* Created using file FILEAA as input */ OPNID(FILEA) FILE(FILEAA)

CALL CLOF DLTOVR

The records retrieved by the program appear as:

Cust 001 002 003 004 Count 3 1 2 2 Amtsum 1500.00 1200.00 1500.00 400.00 Amtavg 500.00 1200.00 750.00 200.00 Amtmax 700.00 1200.00 900.00 300.00

Note: If you specify the GRPFLD parameter, the groups may not appear in ascending sequence. To ensure a specic sequence, you should specify the KEYFLD parameter. Assume you want to print only the summary records in this example in which the Amtsum value is greater than 700.00. Because the Amtsum eld is an aggregate eld for a given customer, use the GRPSLT parameter to specify selection after grouping. Add the GRPSLT parameter:
GRPSLT('AMTSUM *GT 700.00')
Chapter 6. Opening a Database File

149

The records retrieved by your program are:

Cust 001 002 003 Count 3 1 2 Amtsum 1500.00 1200.00 1500.00 Amtavg 500.00 1200.00 750.00 Amtmax 700.00 1200.00 900.00

The Open Query File (OPNQRYF) command supports selection both before grouping (QRYSLT parameter) and after grouping (GRPSLT parameter). Assume you want to select additional customer records in which the Type eld is equal to A. Because Type is a eld in the record format for le FILEA and not an aggregate eld, you add the QRYSLT statement to select before grouping as follows:
QRYSLT('TYPE *EQ "A" ')

Note that elds used for selection do not have to appear in the format processed by the program. The records retrieved by your program are:
Cust 001 002 Count 2 1 Amtsum 800.00 1200.00 Amtavg 400.00 1200.00 Amtmax 500.00 1200.00

Notice the values for CUST 001 changed because the selection took place before the grouping took place. Assume you want to arrange the output by the Amtavg eld in descending sequence, in addition to the previous QRYSLT parameter value. You can do this by changing the KEYFLD parameter on the OPNQRYF command as:
KEYFLD((AMTAVG *DESCEND))

The records retrieved by your program are:

Cust 002 001 Count 1 2 Amtsum 1200.00 800.00 Amtavg 1200.00 400.00 Amtmax 1200.00 500.00

Final Total-Only Processing

Final-total-only processing is a special form of grouping in which you do not specify grouping elds. Only one record is output. All of the special built-in functions for grouping can be specied. You can also specify the selection of records that make up the nal total. Example 1: Simple total processing Assume you have a database le FILEA and decide to create le FINTOT for your nal total record as follows:
FILEA Code Amt FINTOT Count (count of all the selected records) Totamt (total of the amount eld) Maxamt (maximum value in the amount eld)

150

OS/400 DB2 for AS/400 Database Programming V4R3

The FINTOT le is created specically to hold the single record which is created with the nal totals. You would specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FINTOT) TOFILE(FILEA) SHARE(*YES) FILE(FILEA) FORMAT(FINTOT) + MAPFLD((COUNT '%COUNT') + (TOTAMT '%SUM(AMT)') (MAXAMT '%MAX(AMT)')) PGM(PGMG) /* Created using file FINTOT as input */ OPNID(FILEA) FILE(FINTOT)

Example 2: Total-only processing with record selection Assume you want to change the previous example so that only the records where the Code eld is equal to B are in the nal total. You can add the QRYSLT parameter as follows:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FINTOT) TOFILE(FILEA) SHARE(*YES) FILE(FILEA) FORMAT(FINTOT) + QRYSLT('CODE *EQ "B" ') MAPFLD((COUNT '%COUNT') + (TOTAMT '%SUM(AMT)') (MAXAMT '%MAX(AMT)')) PGM(PGMG) /* Created using file FINTOT as input */ OPNID(FILEA) FILE(FINTOT)

You can use the GRPSLT keyword with the nal total function. The GRPSLT selection values you specify determines if you receive the nal total record. Example 3: Total-only processing using a new record format Assume you want to process the new le/format with a CL program. You want to read the le and send a message with the nal totals. You can specify:
DCLF DCL DCL OVRDBF OPNQRYF FILE(FINTOT) &COUNTA *CHAR LEN(7) &TOTAMTA *CHAR LEN(9) FILE(FINTOT) TOFILE(FILEA) SHARE(*YES) FILE(FILEA) FORMAT(FINTOT) MAPFLD((COUNT '%COUNT') + (TOTAMT '%SUM(AMT)'))

RCVF CLOF OPNID(FILEA) CHGVAR &COUNTA &COUNT CHGVAR &TOTAMTA &TOTAMT SNDPGMMSG MSG('COUNT=' *CAT &COUNTA *CAT + ' Total amount=' *CAT &TOTAMTA); DLTOVR FILE(FINTOT)

You must convert the numeric elds to character elds to include them in an immediate message.

Controlling How the System Runs the Open Query File Command
The optimization function allows you to specify how you are going to use the results of the query. When you use the Open Query File (OPNQRYF) command there are two steps where performance considerations exist. The rst step is during the actual processing of the OPNQRYF command itself. This step decides if OPNQRYF is going to use an existing access path or build a new one for this query request. The second step when performance considerations play a role is when the application

Chapter 6. Opening a Database File

151

program is using the results of the OPNQRYF to process the data. (See Appendix D. Query Performance: Design Guidelines and Monitoring for additional design guidelines.) For most batch type functions, you are usually only interested in the total time of both steps mentioned above. Therefore, the default for OPNQRYF is OPTIMIZE(*ALLIO). This means that OPNQRYF will consider the total time it takes for both steps. If you use OPNQRYF in an interactive environment, you may not be interested in processing the entire le. You may want the rst screen full of records to be displayed as quickly as possible. For this reason, you would want the rst step to avoid building an access path, if possible. You might specify OPTIMIZE(*FIRSTIO) in such a situation. If you want to process the same results of OPNQRYF with multiple programs, you would want the rst step to make an efficient open data path (ODP). That is, you would try to minimize the number of records that must be read by the processing program in the second step by specifying OPTIMIZE(*MINWAIT) on the OPNQRYF command. If the KEYFLD or GRPFLD parameters on the OPNQRYF command require that an access path be built when there is no access path to share, the access path is built entirely regardless of the OPTIMIZE entry. Optimization mainly affects selection processing. Example 1: Optimizing for the rst set of records Assume that you have an interactive job in which the operator requests all records where the Code eld is equal to B. Your programs suble contains 15 records per screen. You want to get the rst screen of results to the operator as quickly as possible. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('CODE = "B" ') + SEQONLY(*YES 15) OPTIMIZE(*FIRSTIO) PGM(PGMA) OPNID(FILEA) FILE(FILEA)

The system optimizes handling the query and lls the rst buffer with records before completing the entire query regardless of whether an access path already exists over the Code eld. Example 2: Optimizing to minimize the number of records read Assume that you have multiple programs that will access the same le which is built by the Open Query File (OPNQRYF) command. In this case, you will want to optimize the performance so that the application programs read only the data they are interested in. This means that you want OPNQRYF to perform the selection as efficiently as possible. You could specify:
OVRDBF OPNQRYF CALL POSDBF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) QRYSLT('CODE *EQ "B"') + KEYFLD(CUST) OPTIMIZE(*MINWAIT) PGM(PGMA) OPNID(FILEA) POSITION(*START) PGM(PGMB) OPNID(FILEA) FILE(FILEA)

152

OS/400 DB2 for AS/400 Database Programming V4R3

Considerations for Creating a File and Using the FORMAT Parameter

You must specify a record format name on the FORMAT parameter when you request join processing by specifying multiple entries on the FILE parameter (that is, you cannot specify FORMAT(*FILE)). Also, a record format name is normally specied with the grouping function or when you specify a complex expression on the MAPFLD parameter to dene a derived eld. Consider the following: v The record format name is any name you select. It can differ from the format name in the database le you want to query. v The eld names are any names you select. If the eld names are unique in the database les you are querying, the system implicitly maps the values for any elds with the same name in a queried le record format (FILE parameter) and in the query result format (FORMAT parameter). See Example 1 under Dynamically Joining Database Files without DDS on page 140 for more information. v If the eld names are unique, but the attributes differ between the le specied on the FILE parameter and the le specied on the FORMAT parameter, the data is implicitly mapped. v The correct eld attributes must be used when using the MAPFLD parameter to dene derived elds. For example, if you are using the grouping %SUM function, you must dene a eld that is large enough to contain the total. If not, an arithmetic overow occurs and an exception is sent to the program. v Decimal alignment occurs for all eld values mapped to the record format identied on the FORMAT parameter. Assume you have a eld in the query result record format with 5 digits with 0 decimals, and the value that was calculated or must be mapped to that eld is 0.12345. You will receive a result of 0 in your eld because digits to the right of the decimal point are truncated.

Considerations for Arranging Records

The default processing for the Open Query File (OPNQRYF) command provides records in any order that improves performance and does not conict with the order specied on the KEYFLD parameter. Therefore, unless you specify the KEYFLD parameter to either name specic key elds or specify KEYFLD(*FILE), the sequence of the records returned to your program can vary each time you run the same Open Query File (OPNQRYF) command. When you specify the KEYFLD(*FILE) parameter option for the Open Query File (OPNQRYF) command, and a sort sequence other than *HEX has been specied for the query with the job default or the OPNQRYF SRTSEQ parameter, you can receive your records in an order that does not reect the true le order. If the le is keyed, the querys sort sequence is applied to the key elds of the le and informational message CPI431F is sent. The les sort sequence and alternative collating sequence table are ignored for the ordering, if they exist. This allows users to indicate which elds to apply a sort sequence to without having to list all the eld names. If a sort sequence is not specied for the query (for example, *HEX), ordering is done as it was prior to Version 2 Release 3.

Considerations for DDM Files

The Open Query File (OPNQRYF) command can process DDM les. All les identied on the FILE parameter must exist on the same IBM AS/400 system or
Chapter 6. Opening a Database File

153

System/38 target system. An OPNQRYF which species group processing and uses a DDM le requires that both the source and target system be the same type (either both System/38 or both AS/400 systems).

Considerations for Writing a High-Level Language Program

For the method described under Using an Existing Record Format in the File on page 122 (where the FORMAT parameter is omitted), your high-level language program is coded as if you are directly accessing the database le. Selection or sequencing occurs external to your program, and the program receives the selected records in the order you specied. The program does not receive records that are omitted by your selection values. This same function occurs if you process through a logical le with select/omit values. If you use the FORMAT parameter, your program species the same le name used on the FORMAT parameter. The program is written as if this le contains actual data. If you read the le sequentially, your high-level language can automatically specify that the key elds are ignored. Normally you write the program as if it is reading records in arrival sequence. If the KEYFLD parameter is used on the Open Query File (OPNQRYF) command, you receive a diagnostic message, which can be ignored. If you process the le randomly by keys, your high-level language probably requires a key specication. If you have selection values, it can prevent your program from accessing a record that exists in the database. A Record not found condition can occur on a random read whether the OPNQRYF command was used or whether a logical le created using DDS select/omit logic was used. In some cases, you can monitor exceptions caused by mapping errors such as arithmetic overow, but it is better to dene the attributes of all elds to correctly handle the results.

Messages Sent When the Open Query File (OPNQRYF) Command Is Run
When the OPNQRYF command is run, messages are sent informing the interactive user of the status of the OPNQRYF request. For example, a message would be sent to the user if a keyed access path was built by the OPNQRYF to satisfy the request. The following messages might be sent during a run of the OPNQRYF command:
Message Identier CPI4301 CPI4302 CPI4303 CPI4304 CPI4305 CPI4306 CPI4011 Description Query running. Query running. Query running. Query running. Query running. Query running. file... Query running. processed...

Building access path... Creating copy of file... Selection complete... Sorting copy of file... Building access path from Number of records

154

OS/400 DB2 for AS/400 Database Programming V4R3

To stop these status messages from appearing, see the discussion about message handling in the CL Programming book. When your job is running under debug (using the STRDBG command), messages are sent to your job log that describe the implementation method used to process the OPNQRYF request. These messages provide information about the optimization processing that occurred. They can be used as a tool for tuning the OPNQRYF request to achieve the best performance. The messages are as follows: CPI4321 Access path built for le... CPI4322 Access path built from keyed le... CPI4324 Temporary le built from le... CPI4325 Temporary le built for query CPI4326 File processed in join position... CPI4327 File processed in join position 1. CPI4328 Access path of le used... CPI4329 Arrival sequence used for le... CPI432A Query optimizer timed out... CPI432C All access paths were considered for le... CPI432E Selection elds mapped to different attributes... CPI432F Access path suggestion for le... CPI4338 &1 access path(s) used for bitmap processing of le... Most of the messages provide a reason why the particular option was performed. The second level text on each message gives an extended description of why the option was chosen. Some messages provide suggestions to help improve the performance of the OPNQRYF request.

Using the Open Query File (OPNQRYF) Command for More Than Just Input
The OPNQRYF command supports the OPTION parameter to determine the type of processing. The default is OPTION(*INP), so the le is opened for input only. You can also use other OPTION values on the OPNQRYF command and a high-level language program to add, update, or delete records through the open query le. However, if you specify the UNIQUEKEY, GRPFLD, or GRPSLT

Chapter 6. Opening a Database File

155

parameters, use one of the aggregate functions, or specify multiple les on the FILE parameter, your use of the le is restricted to input only. A join logical le is limited to input-only processing. A view is limited to input-only processing, if group, join, union, or distinct processing is specied in the denition of the view. If you want to change a eld value from the current value to a different value in some of the records in a le, you can use a combination of the OPNQRYF command and a specic high-level language program. For example, assume you want to change all the records where the Flda eld is equal to ABC so that the Flda eld is equal to XYZ. You can specify:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) OPTION(*ALL) QRYSLT('FLDA *EQ "ABC" ') PGM(PGMA) OPNID(FILEA) FILE(FILEA)

Program PGMA processes all records it can read, but the query selection restricts these to records where the Flda eld is equal to ABC. The program changes the eld value in each record to XYZ and updates the record. You can also delete records in a database le using the OPNQRYF command. For example, assume you have a eld in your record that, if equal to X, means the record should be deleted. Your program can be written to delete any records it reads and use the OPNQRYF command to select those to be deleted such as:
OVRDBF OPNQRYF CALL CLOF DLTOVR FILE(FILEA) SHARE(*YES) FILE(FILEA) OPTION(*ALL) QRYSLT('DLTCOD *EQ "X" ') PGM(PGMB) OPNID(FILEA) FILE(FILEA)

You can also add records by using the OPNQRYF command. However, if the query specications include selection values, your program can be prevented from reading the added records because of the selection values.

Date, Time, and Timestamp Comparisons Using the OPNQRYF Command

A date, time, or timestamp value can be compared either with another value of the same data type or with a string representation of that data type. All comparisons are chronological, which means the farther a time is from January 1, 0001, the greater the value of that time. Comparisons involving time values and string representations of time values always include seconds. If the string representation omits seconds, zero seconds are implied. Comparisons involving timestamp values are chronological without regard to representations that might be considered equivalent. Thus, the following predicate is true: TIMESTAMP(1990-02-23-00.00.00) > 1990-02-22-24.00.00 When a character, DBCS-open, or DBCS-either eld or constant is represented as a date, time, or timestamp, the following rules apply:

156

OS/400 DB2 for AS/400 Database Programming V4R3

Date: The length of the eld or literal must be at least 8 if the date format is *ISO, *USA, *EUR, *JIS, *YMD, *MDY, or *DMY. If the date format is *JUL (yyddd), the length of the variable must be at least 6 (includes the separator between yy and ddd). The eld or literal may be padded with blanks. Time: For all of the time formats (*USA, *ISO, *EUR, *JIS, *HMS), the length of the eld or literal must be at least 4. The eld or literal may be padded with blanks. Timestamp: For the timestamp format (yyyy-mm-dd-hh.mm.ss.uuuuuu), the length of the eld or literal must be at least 16. The eld or literal may be padded with blanks.

Date, Time, and Timestamp Arithmetic Using OPNQRYF CL Command

Date, time, and timestamp values can be incremented, decremented, and subtracted. These operations may involve decimal numbers called durations. Following is a denition of durations and a specication of the rules for performing arithmetic operations on date, time, and timestamp values.

Durations
A duration is a number representing an interval of time. The four types of durations are: Labeled Duration A labeled duration represents a specic unit of time as expressed by a number (which can be the result of an expression) used as an operand for one of the seven duration built-in functions: %DURYEAR, %DURMONTH, %DURDAY, %DURHOUR, %DURMINUTE, %DURSEC, or %DURMICSEC. The functions are for the duration of year, month, day, hour, minute, second, and microsecond, respectively. The number specied is converted as if it was assigned to a DECIMAL(15,0) number. A labeled duration can only be used as an operand of an arithmetic operator when the other operand is a value of data type *DATE, *TIME, or *TIMESTP. Thus, the expression HIREDATE + %DURMONTH(2) + %DURDAY(14) is valid, whereas the expression HIREDATE + (%DURMONTH(2) + %DURDAY(14)) is not. In both of these expressions, the labeled durations are %DURMONTH(2) and %DURDAY(14). Date Duration A date duration represents a number of years, months, and days, expressed as a DECIMAL(8,0) number. To be properly interpreted, the number must have the format yyyymmdd, where yyyy represents the number of years, mm the number of months, and dd the number of days. The result of subtracting one date value from another, as in the expression HIREDATE - BRTHDATE, is a date duration. Time Duration A time duration represents a number of hours, minutes, and seconds, expressed as a DECIMAL(6,0) number. To be properly interpreted, the number must have the format hhmmss, where hh represents the number of hours, mm the number of minutes, and ss the number of seconds. The result of subtracting one time value from another is a time duration.
Chapter 6. Opening a Database File

157

Timestamp Duration A timestamp duration represents a number of years, months, days, hours, minutes, seconds, and microseconds, expressed as a DECIMAL(20,6) number. To be properly interpreted, the number must have the format yyyymmddhhmmsszzzzzz, where yyyy, mm, dd, hh, mm, ss, and zzzzzz represent, respectively, the number of years, months, days, hours, minutes, seconds, and microseconds. The result of subtracting one timestamp value from another is a timestamp duration.

Rules for Date, Time, and Timestamp Arithmetic

The only arithmetic operations that can be performed on date and time values are addition and subtraction. If a date or time value is the operand of addition, the other operand must be a duration. The specic rules governing the use of the addition operator with date and time values follow: v If one operand is a date, the other operand must be a date duration or a labeled duration of years, months, or days. v If one operand is a time, the other operand must be a time duration or a labeled duration of hours, minutes, or seconds. v If one operand is a timestamp, the other operand must be a duration. Any type of duration is valid. The rules for the use of the subtraction operator on date and time values are not the same as those for addition because a date or time value cannot be subtracted from a duration, and because the operation of subtracting two date and time values is not the same as the operation of subtracting a duration from a date or time value. The specic rules governing the use of the subtraction operator with date and time values follow: v If the rst operand is a date, the second operand must be a date, a date duration, a string representation of a date, or a labeled duration of years, months, or days. v If the second operand is a date, the rst operand must be a date or a string representation of a date. v If the rst operand is a time, the second operand must be a time, a time duration, a string representation of a time, or a labeled duration of hours, minutes, or seconds. v If the second operand is a time, the rst operand must be a time or string representation of a time. v If the rst operand is a timestamp, the second operand must be a timestamp, a string representation of a timestamp, or a duration. v If the second operand is a timestamp, the rst operand must be a timestamp or a string representation of a timestamp.

Date Arithmetic
Dates can be subtracted, incremented, or decremented. Subtracting Dates: The result of subtracting one date (DATE2) from another (DATE1) is a date duration that species the number of years, months, and days between the two dates. The data type of the result is DECIMAL(8,0). If DATE1 is greater than or equal to DATE2, DATE2 is subtracted from DATE1. If DATE1 is less than DATE2, however, DATE1 is subtracted from DATE2, and the sign of the result is made negative. The following procedural description claries the steps involved in the operation RESULT = DATE1 - DATE2.

158

OS/400 DB2 for AS/400 Database Programming V4R3

If %DAY(DATE2) <= %DAY(DATE1) ; then %DAY(RESULT) = %DAY(DATE1) - %DAY(DATE2). If %DAY(DATE2) > %DAY(DATE1) ; then %DAY(RESULT) = N + %DAY(DATE1) - %DAY(DATE2) ; where N = the last day of %MONTH(DATE2). ; %MONTH(DATE2) is then incremented by 1. If %MONTH(DATE2) <= %MONTH(DATE1) ; then %MONTH(RESULT) = %MONTH(DATE1) - %MONTH(DATE2). If %MONTH(DATE2) > %MONTH(DATE1) ; then %MONTH(RESULT) = 12 + %MONTH(DATE1) - %MONTH(DATE2). ; %YEAR(DATE2) is then incremented by 1. %YEAR(RESULT) = %YEAR(DATE1) - %YEAR(DATE2).

For example, the result of %DATE('3/15/2000') - '12/31/1999' is 215 (or, a duration of 0 years, 2 months, and 15 days). Incrementing and Decrementing Dates: The result of adding a duration to a date, or of subtracting a duration from a date, is itself a date. (For the purposes of this operation, a month denotes the equivalent of a calendar page. Adding months to a date, then, is like turning the pages of a calendar, starting with the page on which the date appears.) The result must fall between the dates January 1, 0001, and December 31, 9999, inclusive. If a duration of years is added or subtracted, only the year portion of the date is affected. The month is unchanged, as is the day unless the result would be February 29 of a year that is not a leap year. In this case, the day is changed to 28. Similarly, if a duration of months is added or subtracted, only months and, if necessary, years are affected. The day portion of the date is unchanged unless the result would not be valid (September 31, for example). In this case, the day is set to the last day of the month. Adding or subtracting a duration of days will, of course, affect the day portion of the date, and potentially the month and year. Date durations, whether positive or negative, may also be added to and subtracted from dates. As with labeled durations, the result is a valid date. When a positive date duration is added to a date, or a negative date duration is subtracted from a date, the date is incremented by the specied number of years, months, and days, in that order. Thus, DATE1 + X, where X is a positive DECIMAL(8,0) number, is equivalent to the expression: DATE1 + %DURYEAR(%YEAR(X)) + %DURMONTH(%MONTH(X)) + %DURDAY(%DAY(X)) When a positive date duration is subtracted from a date, or a negative date duration is added to a date, the date is decremented by the specied number of days, months, and years, in that order. Thus, DATE1 - X, where X is a positive DECIMAL(8,0) number, is equivalent to the expression: DATE1 %DURDAY(%DAY(X)) - %DURMONTH(%MONTH(X)) - %DURYEAR(%YEAR(X))

Chapter 6. Opening a Database File

159

When adding durations to dates, adding one month to a given date gives the same date one month later unless that date does not exist in the later month. In that case, the date is set to that of the last day of the later month. For example, January 28 plus one month gives February 28; and one month added to January 29, 30, or 31 results in either February 28 or, for a leap year, February 29. Note: If one or more months are added to a given date and then the same number of months is subtracted from the result, the nal date is not necessarily the same as the original date.

Time Arithmetic
Times can be subtracted, incremented, or decremented. Subtracting Times: The result of subtracting one time (TIME2) from another (TIME1) is a time duration that species the number of hours, minutes, and seconds between the two times. The data type of the result is DECIMAL(6,0). If TIME1 is greater than or equal to TIME2, TIME2 is subtracted from TIME1. If TIME1 is less than TIME2, however, TIME1 is subtracted from TIME2, and the sign of the result is made negative. The following procedural description claries the steps involved in the operation RESULT = TIME1 - TIME2. If %SECOND(TIME2) <= %SECOND(TIME1) ; then %SECOND(RESULT) = %SECOND(TIME1) - %SECOND(TIME2). If %SECOND(TIME2) > %SECOND(TIME1) ; then %SECOND(RESULT) = 60 + %SECOND(TIME1) - %SECOND(TIME2). ; %MINUTE(TIME2) is then incremented by 1. If %MINUTE(TIME2) <= %MINUTE(TIME1) ; then %MINUTE(RESULT) = %MINUTE(TIME1) - %MINUTE(TIME2). If %MINUTE(TIME2) > %MINUTE(TIME1) ; then %MINUTE(RESULT) = 60 + %MINUTE(TIME1) - %MINUTE(TIME2). ; %HOUR(TIME2) is then incremented by 1. %HOUR(RESULT) = %HOUR(TIME1) - %HOUR(TIME2). For example, the result of %TIME('11:02:26') - '00:32:56' is 102930 (a duration of 10 hours, 29 minutes, and 30 seconds). Incrementing and Decrementing Times: The result of adding a duration to a time, or of subtracting a duration from a time, is itself a time. Any overow or underow of hours is discarded, thereby ensuring that the result is always a time. If a duration of hours is added or subtracted, only the hours portion of the time is affected. The minutes and seconds are unchanged. Similarly, if a duration of minutes is added or subtracted, only minutes and, if necessary, hours are affected. The seconds portion of the time is unchanged. Adding or subtracting a duration of seconds will, of course, affect the seconds portion of the time, and potentially the minutes and hours. Time durations, whether positive or negative, also can be added to and subtracted from times. The result is a time that has been incremented or decremented by the specied number of hours, minutes, and seconds, in that order. TIME1 + X, where X

160

OS/400 DB2 for AS/400 Database Programming V4R3

is a DECIMAL(6,0) number, is equivalent to the expression: TIME1 + %DURHOUR(%HOUR(X)) + %DURMINUTE(%MINUTE(X)) + %DURSEC(%SECOND(X))

Timestamp Arithmetic
Timestamps can be subtracted, incremented, or decremented. Subtracting Timestamps: The result of subtracting one timestamp (TS2) from another (TS1) is a timestamp duration that species the number of years, months, days, hours, minutes, seconds, and microseconds between the two timestamps. The data type of the result is DECIMAL(20,6). If TS1 is greater than or equal to TS2, TS2 is subtracted from TS1. If TS1 is less than TS2, however, TS1 is subtracted from TS2 and the sign of the result is made negative. The following procedural description claries the steps involved in the operation RESULT = TS1 - TS2: If %MICSEC(TS2) <= %MICSEC(TS1) ; then %MICSEC(RESULT) = %MICSEC(TS1) - ; %MICSEC(TS2). If %MICSEC(TS2) > %MICSEC(TS1) ; then %MICSEC(RESULT) = 1000000 + ; %MICSEC(TS1) - %MICSEC(TS2) ; and %SECOND(TS2) is incremented by 1.

The seconds and minutes part of the timestamps are subtracted as specied in the rules for subtracting times: If %HOUR(TS2) <= %HOUR(TS1) ; then %HOUR(RESULT) = %HOUR(TS1) - %HOUR(TS2). If %HOUR(TS2) > %HOUR(TS1) ; then %HOUR(RESULT) = 24 + %HOUR(TS1) - %HOUR(TS2) ; and %DAY(TS2) is incremented by 1.

The date part of the timestamp is subtracted as specied in the rules for subtracting dates. Incrementing and Decrementing Timestamps: The result of adding a duration to a timestamp, or of subtracting a duration from a timestamp, is itself a timestamp. Date and time arithmetic is performed as previously dened, except that an overow or underow of hours is carried into the date part of the result, which must be within the range of valid dates. Microseconds overow into seconds.

Using the Open Query File (OPNQRYF) Command for Random Processing
Most of the previous examples show the OPNQRYF command using sequential processing. Random processing operations (for example, the RPG/400 language operation CHAIN or the COBOL/400 language operation READ) can be used in most cases. However, if you are using the group or unique-key functions, you cannot process the le randomly.
Chapter 6. Opening a Database File

161

Performance Considerations
See Appendix D. Query Performance: Design Guidelines and Monitoring for design guidelines, tips, and techniques for optimizing the performance of a query application. The best performance can occur when the Open Query File (OPNQRYF) command uses an existing keyed sequence access path. For example, if you want to select all the records where the Code eld is equal to B and an access path exists over the Code eld, the system can use the access path to perform the selection (key positioning selection) rather than read the records and select at run time (dynamic selection). The Open Query File (OPNQRYF) command cannot use an existing index when any of the following are true: v The key eld in the access path is derived from a substring function. v The key eld in the access path is derived from a concatenation function. v Both of the following are true of the sort sequence table associated with the query (specied on the SRTSEQ parameter): It is a shared-weight sequence table. It does not match the sequence table associated with the access path (a sort sequence table or an alternate collating sequence table). v Both of the following are true of the sort sequence table associated with the query (specied on the SRTSEQ parameter): It is a unique-weight sequence table. It does not match the sequence table associated with the access path (a sort sequence table or an alternate collating sequence table) when either: - Ordering is specied (KEYFLD parameter). - Record selection exists (QRYSLT parameter) that does not use *EQ, *NE, *CT, %WLDCRD, or %VALUES. - Join selection exists (JFLD parameter) that does not use *EQ or *NE operators. Part of the OPNQRYF processing is to determine what is the fastest approach to satisfying your request. If the le you are using is large and most of the records have the Code eld equal to B, it is faster to use arrival sequence processing than to use an existing keyed sequence access path. Your program will still see the same records. OPNQRYF can only make this type of decision if an access path exists on the Code eld. In general, if your request will include approximately 20% or more of the number of records in the le, OPNQRYF will tend to ignore the existing access paths and read the le in arrival sequence. If no access path exists over the Code eld, the program reads all of the records in the le and passes only the selected records to your program. That is, the le is processed in arrival sequence. The system can perform selection faster than your application program. If no appropriate keyed sequence access path exists, either your program or the system makes the selection of the records you want to process. Allowing the system to perform the selection process is considerably faster than passing all the records to your application program.

162

OS/400 DB2 for AS/400 Database Programming V4R3

This is especially true if you are opening a le for update operations because individual records must be passed to your program, and locks are placed on every record read (in case your program needs to update the record). By letting the system perform the record selection, the only records passed to your program and locked are those that meet your selection values. If you use the KEYFLD parameter to request a specic sequence for reading records, the fastest performance results if an access path already exists that uses the same key specication or if a keyed sequence access path exists that is similar to your specications (such as a key that contains all the elds you specied plus some additional elds on the end of the key). This is also true for the GRPFLD parameter and on the to-elds of the JFLD parameter. If no such access path exists, the system builds an access path and maintains it as long as the le is open in your job. Processing all of the records in a le by an access path that does not already exist is generally not as efficient as using a full record sort, if the number of records to be arranged (not necessarily the total number of records in the le) exceeds 1000 and is greater than 20% of the records in the le. While it is generally faster to build the keyed sequence access path than to do the sort, faster processing allowed by the use of arrival sequence processing normally favors sorting the data when looking at the total job time. If a usable access path already exists, using the access path can be faster than sorting the data. You can use the ALWCPYDTA(*OPTIMIZE) parameter of the Open Query File (OPNQRYF) command to allow the system to use a full record sort if that is the fastest method of processing records. If you do not intend to read all of the query records and if the OPTIMIZE parameter is *FIRSTIO or *MINWAIT, you can specify a number to indicate how many records you intend to retrieve. If the number of records is considerably less than the total number the query is expected to return, the system may select a faster access method. If you use the grouping function, faster performance is achieved if you specify selection before grouping (QRYSLT parameter) instead of selection after grouping (GRPSLT parameter). Only use the GRPSLT parameter for comparisons involving aggregate functions. For most uses of the OPNQRYF command, new or existing access paths are used to access the data and present it to your program. In some cases of the OPNQRYF command, the system must create a temporary le. The rules for when a temporary le is created are complex, but the following are typical cases in which this occurs: v When you specify a dynamic join, and the KEYFLD parameter describes key elds from different physical les. v When you specify a dynamic join and the GRPFLD parameter describes elds from different physical les. v When you specify both the GRPFLD and KEYFLD parameters but they are not the same. v When the elds specied on the KEYFLD parameter total more than 2000 bytes in length. v When you specify a dynamic join and *MINWAIT for the OPTIMIZE parameter.

Chapter 6. Opening a Database File

163

v When you specify a dynamic join using a join logical le and the join type (JDFTVAL) of the join logical le does not match the join type of the dynamic join. v When you specify a logical le and the format for the logical le refers to more than one physical le. v When you specify an SQL view, the system may require a temporary le to contain the results of the view. v When the ALWCPYDTA(*OPTIMIZE) parameter is specied and using a temporary result would improve the performance of the query. When a dynamic join occurs (JDFTVAL(*NO)), OPNQRYF attempts to improve performance by reordering the les and joining the le with the smallest number of selected records to the le with the largest number of selected records. To prevent OPNQRYF from reordering the les, specify JORDER(*FILE). This forces OPNQRYF to join the les in the sequence specify in the OPNQRYF command.

Performance Considerations for Sort Sequence Tables

Grouping, Joining, and Selection
When using an existing index, the optimizer ensures that the attributes of the selection, join, and grouping elds match the attributes of the keys in the existing index. Also, the sort sequence table associated with the query must match the sequence table (a sort sequence table or an alternate collating sequence table) associated with the key eld of the existing index. If the sequence tables do not match, the existing index cannot be used. However, if the sort sequence table associated with the query is a unique-weight sequence table (including *HEX), some additional optimization is possible. The optimizer acts as though no sort sequence table is specied for any grouping elds or any selection or join predicates that use the following operators or functions: v *EQ v v v v *NE *CT %WLDCRD %VALUES

The advantage is that the optimizer is free to use any existing access path where the keys match the eld and the access path either: v Does not contain a sequence table. v Contains a unique-weight sequence table (the table does not have to match the unique-weight sort sequence table associated with the query).

Ordering
For ordering elds, the optimizer is not free to use any existing access path. The sort sequence tables associated with the index and the query must match unless the optimizer chooses to do a sort to satisfy the ordering request. When a sort is used, the translation is performed during the sort, leaving the optimizer free to use any existing access path that meets the selection criteria.

164

OS/400 DB2 for AS/400 Database Programming V4R3

Examples
In the following examples, assume that three access paths (indices) exist over the JOB eld. These access paths use the following sort sequence tables: 1. SRTSEQ(*HEX) 2. SRTSEQ(*LANGIDUNQ) LANGID(ENU) 3. SRTSEQ(*LANGIDSHR) LANGID(ENU) Example 1: EQ selection with no sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"') SRTSEQ(*HEX)

The optimizer can use index 1 (*HEX) or 2 (*LANGIDUNQ). Example 2: EQ selection with unique-weight sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"') SRTSEQ(*LANGIDUNQ) LANGID(ENU)

The optimizer can use index 1 (*HEX) or 2 (*LANGIDUNQ). Example 3: EQ selection with shared-weight sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"') SRTSEQ(*LANGIDSHR) LANGID(ENU)

The optimizer can only use index 3 (*LANGIDSHR). Example 4: GT selection with unique-weight sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *GT "MGR"') SRTSEQ(*LANGIDUNQ) LANGID(ENU)

The optimizer can only use index 2 (*LANGIDUNQ). Example 5: Join selection with unique-weight sequence table.
OPNQRYF FILE((STAFF1)(STAFF2)) JFLD(1/JOB 2/JOB *EQ) SRTSEQ(*LANGIDUNQ) LANGID(ENU)

The optimizer can use index 1 (*HEX) or 2 (*LANGIDUNQ). Example 6: Join selection with shared-weight sequence table.
OPNQRYF FILE((STAFF1)(STAFF2)) JFLD(1/JOB 2/JOB *EQ) SRTSEQ(*LANGIDSHR) LANGID(ENU)

The optimizer can only use index 3 (*LANGIDSHR). Example 7: Ordering with no sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"') SRTSEQ(*HEX) KEYFLD(JOB)

The optimizer can only use index 1 (*HEX). Example 8: Ordering with unique-weight sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"') SRTSEQ(*LANGIDUNQ) LANGID(ENU) KEYFLD(JOB)

The optimizer can only use index 2 (*LANGIDUNQ). Example 9: Ordering with shared-weight sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"') SRTSEQ(*LANGIDSHR) LANGID(ENU) KEYFLD(JOB)
Chapter 6. Opening a Database File

165

The optimizer can only use index 3 (*LANGIDSHR). Example 10: Ordering with ALWCPYDTA and unique-weight sequence table.
OPNQRYF FILE(STAFF) QRYSLT('JOB *EQ "MGR"') SRTSEQ(*LANGIDUNQ) LANGID(ENU) KEYFLD(JOB) ALWCPYDTA(*OPTIMIZE)

The optimizer can use index 1 (*HEX) or 2 (*LANGIDUNQ) for selection. Ordering is done during the sort using a *LANGIDUNQ sequence table. Example 11: Grouping with no sequence table
OPNQRYF FILE(STAFF) GRPFLD(JOB) SRTSEQ(*HEX)

The optimizer can use index 1 (*HEX) or 2 (*LANGIDUNQ). Example 12: Grouping with unique-weight sequence table.
OPNQRYF FILE(STAFF) GRPFLD(JOB) SRTSEQ(*LANGIDUNQ) LANGID(ENU)

The optimizer can use index 1 (*HEX) or 2 (*LANGIDUNQ). Example 13: Grouping with shared-weight sequence table.
OPNQRYF FILE(STAFF) GRPFLD(JOB) SRTSEQ(*LANGIDSHR) LANGID(ENU)

The optimizer can only use index 3 (*LANGIDSHR).

More Examples
In the following examples, the access paths (numbers 1, 2, and 3) from the examples 1 through 13 still exist over the JOB eld. In examples 14 through 20 there are access paths (numbers 4, 5, and 6) built over the JOB and SALARY elds. The access paths use the following sort sequence tables: 1. SRTSEQ(*HEX) 2. SRTSEQ(*LANGIDUNQ) LANGID(ENU) 3. SRTSEQ(*LANGIDSHR) LANGID(ENU) 4. SRTSEQ(*HEX) 5. SRTSEQ(*LANGIDUNQ) LANGID(ENU) 6. SRTSEQ(*LANGIDSHR) LANGID(ENU) Example 14: Ordering and grouping on the same elds with a unique-weight sequence table.
OPNQRYF FILE(STAFF) SRTSEQ(*LANGIDUNQ) LANGID(ENU) GRPFLD(JOB SALARY) KEYFLD((JOB)(SALARY))

The optimizer can use index 5 (*LANGIDUNQ) to satisfy both the grouping and ordering requirements. If index 5 did not exist, the optimizer would create an index using the *LANGIDUNQ sequence table. Example 15: Ordering and grouping on the same elds with ALWCPYDTA and a unique-weight sequence table.

166

OS/400 DB2 for AS/400 Database Programming V4R3

OPNQRYF FILE(STAFF) ALWCPYDTA(*OPTIMIZE) SRTSEQ(*LANGIDUNQ) LANGID(ENU) GRPFLD(JOB SALARY) KEYFLD((JOB)(SALARY))

The optimizer can use index 5 (*LANGIDUNQ) to satisfy both the grouping and ordering requirements. If index 5 does not exist, the optimizer would either: v Create an index using a *LANGIDUNQ sequence table. v Use index 4 (*HEX) to satisfy the grouping and perform a sort to satisfy the ordering. Example 16: Ordering and grouping on the same elds with a shared-weight sequence table.
OPNQRYF FILE(STAFF) SRTSEQ(*LANGIDSHR) LANGID(ENU) GRPFLD(JOB SALARY) KEYFLD((JOB)(SALARY))

The optimizer can use index 6 (*LANGIDSHR) to satisfy both the grouping and ordering requirements. If index 6 did not exist, the optimizer would create an index using a *LANGIDSHR sequence table. Example 17: Ordering and grouping on the same elds with ALWCPYDTA and a shared-weight sequence table.
OPNQRYF FILE(STAFF) ALWCPYDTA(*OPTIMIZE) SRTSEQ(*LANGIDSHR) LANGID(ENU) GRPFLD(JOB SALARY) KEYFLD((JOB)(SALARY))

The optimizer can use index 6 (*LANGIDSHR) to satisfy both the grouping and ordering requirements. If index 6 did not exist, the optimizer would create an index using a *LANGIDSHR sequence table. Example 18: Ordering and grouping on different elds with a unique-weight sequence table.
OPNQRYF FILE(STAFF) SRTSEQ(*LANGIDUNQ) LANGID(ENU) GRPFLD(JOB SALARY) KEYFLD((SALARY)(JOB))

The optimizer can use index 4 (*HEX) or 5 (*LANGIDUNQ) to satisfy the grouping requirements. The grouping results are put into a temporary le. A temporary index using a *LANGIDUNQ sequence table is built over the temporary result le to satisfy the ordering requirement. Example 19: Ordering and grouping on different elds with ALWCPYDTA and a unique-weight sequence table.
OPNQRYF FILE(STAFF) ALWCPYDTA(*OPTIMIZE) SRTSEQ(*LANGIDUNQ) LANGID(ENU) GRPFLD(JOB SALARY) KEYFLD((SALARY)(JOB))

The optimizer can use index 4 (*HEX) or 5 (*LANGIDUNQ) to satisfy the grouping requirement. A sort then satises the ordering requirement. Example 20: Ordering and grouping on different elds with ALWCPYDTA and a shared-weight sequence table.
OPNQRYF FILE(STAFF) ALWCPYDTA(*OPTIMIZE) SRTSEQ(*LANGIDSHR) LANGID(ENU) GRPFLD(JOB SALARY) KEYFLD((SALARY)(JOB))

Chapter 6. Opening a Database File

167

The optimizer can use index 6 (*LANGIDSHR) to satisfy the grouping requirement. A sort then satises the ordering requirement.

Performance Comparisons with Other Database Functions

The Open Query File (OPNQRYF) command uses the same database support as logical les and join logical les. Therefore, the performance of functions like building a keyed access path or doing a join operation will be the same. The selection functions done by the OPNQRYF command (for the QRYSLT and GRPSLT parameters) are similar to logical le select/omit. The main difference is that for the OPNQRYF command, the system decides whether to use access path selection or dynamic selection (similar to omitting or specifying the DYNSLT keyword in the DDS for a logical le), as a result of the access paths available on the system and what value was specied on the OPTIMIZE parameter.

Considerations for Field Use

When the grouping function is used, all elds in the record format for the open query le (FORMAT parameter) and all key elds (KEYFLD parameter) must either be grouping elds (specied on the GRPFLD parameter) or mapped elds (specied on the MAPFLD parameter) that are dened using only grouping elds, constants, and aggregate functions. The aggregate functions are: %AVG, %COUNT, %MAX (using only one operand), %MIN (using only one operand), %STDDEV, %SUM, and %VAR. Group processing is required in the following cases: v When you specify grouping eld names on the GRPFLD parameter v When you specify group selection values on the GRPSLT parameter v When a mapped eld that you specied on the MAPFLD parameter uses an aggregate function in its denition Fields contained in a record format, identied on the FILE parameter, and dened (in the DDS used to create the le) with a usage value of N (neither input nor output) cannot be specied on any parameter of the OPNQRYF command. Only elds dened as either I (input-only) or B (both input and output) usage can be specied. Any elds with usage dened as N in the record format identied on the FORMAT parameter are ignored by the OPNQRYF command. Fields in the open query le records normally have the same usage attribute (input-only or both input and output) as the elds in the record format identied on the FORMAT parameter, with the exceptions noted below. If the le is opened for any option (OPTION parameter) that includes output or update and any usage, and if any B (both input and output) eld in the record format identied on the FORMAT parameter is changed to I (input only) in the open query le record format, then an information message is sent by the OPNQRYF command. If you request join processing or group processing, or if you specify UNIQUEKEY processing, all elds in the query records are given input-only use. Any mapping from an input-only eld from the le being processed (identied on the FILE parameter) is given input-only use in the open query le record format. Fields dened using the MAPFLD parameter are normally given input-only use in the open query le. A eld dened on the MAPFLD parameter is given a value that matches the use of its constituent eld if all of the following are true: v Input-only is not required because of any of the conditions previously described in this section.

168

OS/400 DB2 for AS/400 Database Programming V4R3

v The eld-denition expression specied on the MAPFLD parameter is a eld name (no operators or built-in functions). v The eld used in the eld-denition expression exists in one of the le, member, or record formats specied on the FILE parameter (not in another eld dened using the MAPFLD parameter). v The base eld and the mapped eld are compatible eld types (the mapping does not mix numeric and character eld types, unless the mapping is between zoned and character elds of the same length). v If the base eld is binary with nonzero decimal precision, the mapped eld must also be binary and have the same precision.

Considerations for Files Shared in a Job

In order for your application program to use the open data path built by the Open Query File (OPNQRYF) command, your program must share the query le. If your program does not open the query le as shared, then it actually does a full open of the le it was originally compiled to use (not the query open data path built by the OPNQRYF command). Your program will share the query open data path, depending on the following conditions: v Your application program must open the le as shared. Your program meets this condition when the rst or only member queried (as specied on the FILE parameter) has an attribute of SHARE(*YES). If the rst or only member has an attribute of SHARE(*NO), then you must specify SHARE(*YES) in an Override with Database File (OVRDBF) command before calling your program. v The le opened by your application program must have the same name as the le opened by the OPNQRYF command. Your program meets this condition when the le specied in your program has the same le and member name as the rst or only member queried (as specied on the FILE parameter). If the rst or only member has a different name, then you must specify an Override with Database File (OVRDBF) command of the name of the le your program was compiled against to the name of the rst or only member queried. v Your program must be running in the same activation group to which the query open data path (ODP) is scoped. If the query ODP is scoped to the job, your program may run in any activation group within the job. The OPNQRYF command never shares an existing open data path in the job or activation group. A request to open a query le fails with an error message if the open data path has the same library, le, and member name that is in the open request, and if either of the following is true: v OPNSCOPE(*ACTGRPDFN) or OPNSCOPE(*ACTGRP) is specied for the OPNQRYF command, and the open data path is scoped to the same activation group or job from which the OPNQRYF command is run. v OPNSCOPE(*JOB) is specied for the OPNQRYF command, and the open data path is scoped to the same job from which the OPNQRYF command is run. Subsequent shared opens adhere to the same open options (such as SEQONLY) that were in effect when the OPNQRYF command was run. See Sharing Database Files in the Same Job or Activation Group on page 104 for more information about sharing les in a job or activation group.

Chapter 6. Opening a Database File

169

Considerations for Checking If the Record Format Description Changed

If record format level checking is indicated, the format level number of the open query le record format (identied on the FORMAT parameter) is checked against the record format your program was compiled against. This occurs when your program shares the previously opened query le. Your programs shared open is checked for record format level if the following conditions are met: v The rst or only le queried (as specied on the FILE parameter) must have the LVLCHK(*YES) attribute. v There must not be an override of the rst or only le queried to LVLCHK(*NO).

Other Run Time Considerations

Overrides can change the name of the le, library, and member that should be processed by the open query le. (However, any parameter values other than TOFILE, MBR, LVLCHK, INHWRT, or SEQONLY specied on an Override with Database File (OVRDBF) command are ignored by the OPNQRYF command.) If a name change override applies to the rst or only member queried, any additional overrides must be against the new name, not the name specied for the FILE parameter on the OPNQRYF command.

Copying from an Open Query File

The Copy from Query File (CPYFRMQRYF) command can be used to copy from an open query le to another le or to print a formatted listing of the records. Any open query le, except those using distributed data management (DDM) les, specied with the input, update, or all operation value on the FILE parameter of the Open Query File (OPNQRYF) command can be copied using the CPYFRMQRYF command. The CPYFRMQRYF command cannot be used to copy to logical les. For more information, see the Data Management book. Although the CPYFRMQRYF command uses the open data path of the open query le, it does not open the le. Consequently, you do not have to specify SHARE(*YES) for the database le you are copying. The following are examples of how the OPNQRYF and CPYFRMQRYF commands can be used. Example 1: Building a le with a subset of records Assume you want to create a le from the CUSTOMER/ADDRESS le containing only records where the value of the STATE eld is Texas. You can specify the following:
OPNQRYF FILE(CUSTOMER/ADDRESS) QRYSLT('STATE *EQ "TEXAS"') CPYFRMQRYF FROMOPNID(ADDRESS) TOFILE(TEXAS/ADDRESS) CRTFILE(*YES)

Example 2: Printing records based on selection Assume you want to print all records from FILEA where the value of the CITY eld is Chicago. You can specify the following:
OPNQRYF FILE(FILEA) QRYSLT('CITY *EQ "CHICAGO"') CPYFRMQRYF FROMOPNID(FILEA) TOFILE(*PRINT)

Example 3: Copying a subset of records to a diskette

170

OS/400 DB2 for AS/400 Database Programming V4R3

Assume you want to copy all records from FILEB where the value of FIELDB is 10 to a diskette. You can specify the following:
OPNQRYF FILE(FILEB) QRYSLT('FIELDB *EQ "10"') OPNID(MYID) CPYFRMQRYF FROMOPNID(MYID) TOFILE(DISK1)

Example 4: Creating a copy of the output of a dynamic join Assume you want to create a physical le that has the format and data of the join of FILEA and FILEB. Assume the les contain the following elds:
FILEA Cust Name Addr FILEB Cust Amt JOINAB Cust Name Amt

The join eld is Cust, which exists in both les. To join the les and save a copy of the results in a new physical le MYLIB/FILEC, you can specify:
OPNQRYF FILE(FILEA FILEB) FORMAT(JOINAB) + JFLD((FILEA/CUST FILEB/CUST)) + MAPFLD((CUST 'FILEA/CUST')) OPNID(QRYFILE) CPYFRMQRYF FROMOPNID(QRYFILE) TOFILE(MYLIB/FILEC) CRTFILE(*YES)

The le MYLIB/FILEC will be created by the CPYFRMQRYF command. The le will have le attributes like those of FILEA although some le attributes may be changed. The format of the le will be like JOINAB. The le will contain the data from the join of FILEA and FILEB using the Cust eld. File FILEC in library MYLIB can be processed like any other physical le with CL commands, such as the Display Physical File Member (DSPPFM) command and utilities, such as Query. For more information about the CPYFRMQRYF command and other copy commands, see the Data Management book.

Typical Errors When Using the Open Query File (OPNQRYF) Command
Several functions must be correctly specied for the OPNQRYF command and your program to get the correct results. The Display Job (DSPJOB) command is your most useful tool if problems occur. This command supports both the open les option and the le overrides option. You should look at both of these if you are having problems. These are the most common problems and how to correct them: v Shared open data path (ODP). The OPNQRYF command operates through a shared ODP. In order for the le to process correctly, the member must be opened for a shared ODP. If you are having problems, use the open les option on the DSPJOB command to determine if the member is opened and has a shared ODP. There are normally two reasons that the le is not open: The member to be processed must be SHARE(*YES). Either use an Override with Database File (OVRDBF) command or permanently change the member. The le is closed. You have run the OPNQRYF command with the OPNSCOPE(*ACTGRPDFN) or TYPE(*NORMAL) parameter option from a program that was running in the default activation group at a higher level in the call stack than the program that is getting an error message or that is simply running the Reclaim Resources (RCLRSC) command. This closes the open query le because it was opened from a program at a higher level in the call stack than the program that ran the RCLRSC command. If the open query
Chapter 6. Opening a Database File

171

le was closed, you must run the OPNQRYF command again. Note that when using the OPNQRYF command with the TYPE(*NORMAL) parameter option on releases prior to Version 2 Release 3, the open query le is closed even if it was opened from the same program that reclaims the resources. v Level check. Level checking is normally used because it ensures that your program is running against the same record format that the program was compiled with. If you are experiencing level check problems, it is normally because of one of the following: The record format was changed since the program was created. Creating the program again should correct the problem. An override is directing the program to an incorrect le. Use the le overrides option on the DSPJOB command to ensure that the overrides are correctly specied. The FORMAT parameter is needed but is either not specied or incorrectly specied. When a le is processed with the FORMAT parameter, you must ensure: - The Override with Database File (OVRDBF) command, used with the TOFILE parameter, describes the rst le on the FILE parameter of the Open Query File (OPNQRYF) command. - The FORMAT parameter identies the le that contains the format used to create the program. The FORMAT parameter is used to process a format from a different le (for example, for group processing), but SHARE(*YES) was not requested on the OVRDBF command. v The le to be processed is at end of le. The normal use of the OPNQRYF command is to process a le sequentially where you can only process the le once. At that point, the position of the le is at the end of the le and you will not receive any records if you attempt to process it again. To process the le again from the start, you must either run the OPNQRYF command again or reposition the le before processing. You can reposition the le by using the Position Database File (POSDBF) command, or through a high-level language program statement. v No records exist. This can be caused when you use the FORMAT keyword, but do not specify the OVRDBF command. v Syntax errors. The system found an error in the specication of the OPNQRYF command. v Operation not valid. The denition of the query does not include the KEYFLD parameter, but the high-level language program attempts to read the query le using a key eld. v Get option not valid. The high-level language program attempted to read a record or set a record position before the current record position, and the query le used either the group by option, the unique key option, or the distinct option on the SQL statement.

172

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 7. Basic Database File Operations

The basic database le operations that can be performed in a program are discussed in this chapter. The operations include: setting a position in the database le, reading records from the le, updating records in the le, adding records to the le, and deleting records from the le.

Setting a Position in the File

After a le is opened by a job, the system maintains a position in the le for that job. The le position is used in processing the le. For example, if a program does a read operation requesting the next sequential record, the system uses the le position to determine which record to return to the program. The system will then set the le position to the record just read, so that another read operation requesting the next sequential record will return the correct record. The system keeps track of all le positions for each job. In addition, each job can have multiple positions in the same le. The le position is rst set to the position specied in the POSITION parameter on the Override with Database File (OVRDBF) command. If you do not use an OVRDBF command, or if you take the default for the POSITION parameter, the le position is set just before the rst record in the members access path. A program can change the current le position by using the appropriate high-level language program le positioning operation (for example, SETLL in the RPG/400 language or START in the COBOL/400 language). A program can also change the le position by using the CL Position Database File (POSDBF) command. Note: File positioning by means of the Override with Database File (OVRDBF) command does not occur until the next time the le is opened. Because a le can be opened only once within a CL program, this command cannot be used within a single CL program to affect what will be read through the RCVF command. At end of le, after the last read, the le member is positioned to *START or *END le position, depending on whether the program was reading forward or backward through the le. The following diagram shows *START and *END le positions.
*START File Position after Open (default) Record1 Record2 Record3 *END File Position after End of File (reading forward)

Only a read operation, force-end-of-data operation, high-level language positioning operation, or specic CL command to change the le position can change the le
Copyright IBM Corp. 1997, 1998

173

position. Add, update, and delete operations do not change the le position. After a read operation, the le is positioned to the new record. This record is then returned to your program. After the read operation is completed, the le is positioned at the record just returned to your program. If the member is open for input, a force-end-of-data operation positions the le after the last record in the le (*END) and sends the end-of-le message to your program. For sequential read operations, the current le position is used to locate the next or previous record on the access path. For read-by-key or read-by-relative-recordnumber operations, the le position is not used. If POSITION(*NONE) is specied at open time, no starting le position is set. In this case, you must establish a le position in your program, if you are going to read sequentially. If end-of-le delay was specied for the le on an Override With Database File (OVRDBF) command, the le is not positioned to *START or *END when the program reads the last record. The le remains positioned at the last record read. A le with end-of-le delay processing specied is positioned to *START or *END only when a force-end-of-data (FEOD) occurs or a controlled job end occurs. For more information about end-of-le delay, see Waiting for More Records When End of File Is Reached on page 177. You can also use the Position Database File (POSDBF) command to set or change the current position in your le for les opened using either the Open Database File (OPNDBF) command or the Open Query File (OPNQRYF) command.

Reading Database Records

The AS/400 system provides a number of ways to read database records. The next sections describe those ways in detail. (Some high-level languages do not support all of the read operations available on the system. See your high-level language guide for more information about reading database records.)

Reading Database Records Using an Arrival Sequence Access Path

The system performs the following read operations based on the operations you specify using your high-level language. These operations are allowed if the le was dened with an arrival sequence access path; or if the le was dened with a keyed sequence access path with the ignore-keyed-sequence-access-path option specied in the program, on the Open Database File (OPNDBF) command, or on the Open Query File (OPNQRYF) command. See Ignoring the Keyed Sequence Access Path on page 100 for more details about the option to ignore a keyed sequence access path. Note: Your high-level language may not allow all of the following read operations. Refer to your high-level language guide to determine which operations are allowed by the language.

Read Next
Positions the le to and gets the next record that is not deleted in the arrival sequence access path. Deleted records between the current position in the le and

174

OS/400 DB2 for AS/400 Database Programming V4R3

the next active record are skipped. (The READ statement in the RPG/400 language and the READ NEXT statement in the COBOL/400 language are examples of this operation.)

Read Previous
Positions the le to and gets the previous active record in the arrival sequence access path. Deleted records between the current le position and the previous active record are skipped. (The READP statement in the RPG/400 language and the READ PRIOR statement in the COBOL/400 language are examples of this operation.)

Read First
Positions the le to and gets the rst active record in the arrival sequence access path.

Read Last
Positions the le to and gets the last active record in the arrival sequence access path.

Read Same
Gets the record that is identied by the current position in the le. The le position is not changed.

Read by Relative Record Number

Positions the le to and gets the record in the arrival sequence access path that is identied by the relative record number. The relative record number must identify an active record and must be less than or equal to the largest active relative record number in the member. This operation also reads the record in the arrival sequence access path identied by the current le position plus or minus a specied number of records. (The CHAIN statement in the RPG/400 language and the READ statement in the COBOL/400 language are examples of this operation.) Special consideration should be given to creating or changing a le to reuse deleted records if the le is processed by relative record processing. For more information, see Reusing Deleted Records on page 99.

Reading Database Records Using a Keyed Sequence Access Path

The system performs the following read operations based on the statements you specify using your high-level language. These operations can be used with a keyed sequence access path to get database records. When a keyed sequence access path is used, a read operation cannot position to the storage occupied by a deleted record. Note: Your high-level language may not allow all of the following operations. Refer to your high-level language guide to determine which operations are allowed by the language.

Chapter 7. Basic Database File Operations

175

Read Next
Gets the next record on the keyed sequence access path. If a record format name is specied, this operation gets the next record in the keyed sequence access path that matches the record format. The current position in the le is used to locate the next record. (The READ statement in the RPG/400 language and the READ NEXT statement in the COBOL/400 language are examples of this operation.)

Read Previous
Gets the previous record on the keyed sequence access path. If a record format name is specied, this operation gets the previous record on the keyed sequence access path that matches the record format. The current position in the le is used to locate the previous record. (The READP statement in the RPG/400 language and the READ PRIOR statement in the COBOL/400 language are examples of this operation.)

Read First
Gets the rst record on the keyed sequence access path. If a record format name is specied, this operation gets the rst record on the access path with the specied format name.

Read Last
Gets the last record on the keyed sequence access path. If a record format name is specied, this operation gets the last record on the access path with the specied format name.

Read Same
Gets the record that is identied by the current le position. The position in the le is not changed.

Read by Key
Gets the record identied by the key value. Key operations of equal, equal or after, equal or before, read previous key equal, read next key equal, after, or before can be specied. If a format name is specied, the system searches for a record of the specied key value and record format name. If a format name is not specied, the entire keyed sequence access path is searched for the specied key value. If the key denition for the le includes multiple key elds, a partial key can be specied (you can specify either the number of key elds or the key length to be used). This allows you to do generic key searches. If the program does not specify a number of key elds, the system assumes a default number of key elds. This default varies depending on if a record format name is passed by the program. If a record format name is passed, the default number of key elds is the total number of key elds dened for that format. If a record format name is not passed, the default number of key elds is the maximum number of key elds that are common across all record formats in the access path. The program must supply enough key data to match the number of key elds assumed by the system. (The CHAIN statement in the RPG/400 language and the READ statement in the COBOL/400 language are examples of this operation.)

176

OS/400 DB2 for AS/400 Database Programming V4R3

Read by Relative Record Number

For a keyed sequence access path, the relative record number can be used. This is the relative record number in the arrival sequence, even though the member opened has a keyed sequence access path. If the member contains multiple record formats, a record format name must be specied. In this case, you are requesting a record in the associated physical le member that matches the record format specied. If the member opened contains select/omit statements and the record identied by the relative record number is omitted from the keyed sequence access path, an error message is sent to your program and the operation is not allowed. After the operation is completed, the le is positioned to the key value in the keyed sequence access path that is contained in the physical record, which was identied by the relative record number. This operation also gets the record in the keyed sequence access path identied by the current le position plus or minus some number of records. (The CHAIN statement in the RPG/400 language and the READ statement in the COBOL/400 language are examples of this operation.)

Read when Logical File Shares an Access Path with More Keys
When the FIFO, LIFO, or FCFO keyword is not specied in the data description specications (DDS) for a logical le, the logical le can implicitly share an access path that has more keys than the logical le being created. This sharing of a partial set of keys from an existing access path can lead to perceived problems for database read operations that use these partially shared keyed sequence access paths. The problems will appear to be: v Records that should be read, are never returned to your program v Records are returned to your program multiple times What is actually happening is that your program or another currently active program is updating the physical le elds that are keys within the partially shared keyed sequence access path, but that are not actual keys for the logical le that is being used by your program (the elds being updated are beyond the number of keys known to the logical le being used by your program). The updating of the actual key elds for a logical le by your program or another program has always yielded the above results. The difference with partially shared keyed sequence access paths is that the updating of the physical le elds that are keys beyond the number of keys known to the logical le can cause the same consequences. If these consequences caused by partially shared keyed sequence access paths are not acceptable, the FIFO, LIFO, or FCFO keyword can be added to the DDS for the logical le, and the logical le created again.

Waiting for More Records When End of File Is Reached

End-of-le delay is a method of continuing to read sequentially from a database le (logical or physical) after an end-of-le condition occurs. When an end-of-le condition occurs on a le being read sequentially (for example, next/previous record) and you have specied an end-of-le delay time (EOFDLY parameter on the Override with Database File [OVRDBF] command), the system waits for the time you specied. At the end of the delay time, another read is done to determine if any new records were added to the le. If records were added, normal record processing is done until an end-of-le condition occurs again. If records were not added to the le, the system waits again for the time specied. Special consideration should be taken when using end-of-le delay on a logical le with
Chapter 7. Basic Database File Operations

177

select/omit specications, opened so that the keyed sequence access path is not used. In this case, once end-of-le is reached, the system retrieves only those records added to a based-on physical le that meet the select/omit specications of the logical le. Also, special consideration should be taken when using end-of-le delay on a le with a keyed sequence access path, opened so that the keyed sequence access path is used. In this case, once end-of-le is reached, the system retrieves only those records added to the le or those records updated in the le that meet the specication of the read operation using the keyed sequence access path. For example, end-of-le delay is used on a keyed le that has a numeric key eld in ascending order. An application program reads the records in the le using the keyed sequence access path. The application program performs a read next operation and gets a record that has a key value of 99. The application program performs another read next and no more records are found in the le, so the system attempts to read the le again after the specied end-of-le delay time. If a record is added to the le or a record is updated, and the record has a key value less than 99, the system does not retrieve the record. If a record is added to the le or a record is updated and the record has a key value greater than or equal to 99, the system retrieves the record. For end-of-le delay times equal to or greater than 10 seconds, the job is eligible to be removed from main storage during the wait time. If you do not want the job eligible to be moved from main storage, specify PURGE(*NO) on the Create Class (CRTCLS) command for the CLASS the job is using. To indicate which jobs have an end-of-le delay in progress, the status eld of the Work with Active Jobs (WRKACTJOB) display shows an end-of-le wait or end-of-le activity level for jobs that are waiting for a record. If a job uses end-of-le-delay and commitment control, it can hold its record locks for a longer period of time. This increases the chances that some other job can try to access those same records and be locked out. For that reason, be careful when using end-of-le-delay and commitment control in the same job. If a le is shared, the Override with Database File (OVRDBF) command specifying an end-of-le delay must be requested before the rst open of the le because overrides are ignored that are specied after the shared le is opened. There are several ways to end a job that is waiting for more records because of an end-of-le-delay specied on the Override with Database File (OVRDBF) command: v Write a record to the le with the end-of-le-delay that will be recognized by the application program as a last record. The application program can then specify a force-end-of-data (FEOD) operation. An FEOD operation allows the program to complete normal end-of-le processing. v Do a controlled end of a job by specifying OPTION(*CNTRLD) on the End Job (ENDJOB) command, with a DELAY parameter value time greater than the EOFDLY time. The DELAY parameter time specied must allow time for the EOFDLY time to run out, time to process any new records that have been put in the le, and any end-of-le processing required in your application. After new records are processed, the system signals end of le, and a normal end-of-le condition occurs.

178

OS/400 DB2 for AS/400 Database Programming V4R3

v Specify OPTION(*IMMED) on the End Job (ENDJOB) command. No end-of-le processing is done. v If the job is interactive, press the System Request key to end the last request. The following is an example of end-of-le delay operation:
User Program OVRDBF FILEA EOFDLY (60) Data Management

Read FILEA

No

EOF

Yes

Data Management Read to FILEA

Process

EOF Processing

No

EOF

Yes

Return Record to Program EOFDLY

No

Yes

Return EOF Condition to Program

Wait EOFDLY Time

RSLH300-1

The actual processing of the EOFDLY parameter is more complex than shown because it is possible to force a true end-of-le if OPTION(*CNTRLD) on the End Job (ENDJOB) command is used with a long delay time. The job does not become active whenever a new record is added to the le. The job becomes active after the specied end-of-le delay time ends. When the job becomes active, the system checks for any new records. If new records were added, the application program gets control and processes all new records, then waits again. Because of this, the job takes on the characteristic of a batch job when it is processing. For example, it normally processes a batch of requests. When the batch
Chapter 7. Basic Database File Operations

179

is completed, the job becomes inactive. If the delay is small, you can cause excessive system overhead because of the internal processing required to start the job and check for new records. Normally, only a small amount of overhead is used for a job waiting during end-of-le delay. Note: When the job is inactive (waiting) it is in a long-wait status, which means it was released from an activity level. After the long-wait status is satised, the system reschedules the job in an activity level. (See the Work Management book for more information about activity levels.)

Releasing Locked Records

The system automatically releases a locked record when the record is updated, deleted, or when you read another record in the le. However, you may want to release a locked record without performing these operations. Some high-level languages support an operation to release a locked record. See your high-level language guide for more information about releasing record locks. Note: The rules for locking are different if your job is running under commitment control. See the Backup and Recovery book for more details.

Updating Database Records

The update operation allows you to change an existing database record in a logical or physical le. (The UPDAT statement in the RPG/400 language and the REWRITE statement in the COBOL/400 language are examples of this type operation.) Before you update a database record, the record must rst be read and locked. The lock is obtained by specifying the update option on any of the read operations listed under the Reading Database Records Using an Arrival Sequence Access Path on page 174 or Reading Database Records Using a Keyed Sequence Access Path on page 175. If you issue several read operations with the update option specied, each read operation releases the lock on the previous record before attempting to locate and lock the new record. When you do the update operation, the system assumes that you are updating the currently locked record. Therefore, you do not have to identify the record to be updated on the update operation. After the update operation is done, the system releases the lock. Note: The rules for locking are different if your job is running under commitment control. See the Backup and Recovery book for more details. If the update operation changes a key eld in an access path for which immediate maintenance is specied, the access path is updated if the high-level language allows it. (Some high-level languages do not allow changes to the key eld in an update operation.) If you request a read operation on a record that is already locked for update and if your job is running under a commitment control level of *ALL or *CS (cursor stability), then you must wait until the record is released or the time specied by the WAITRCD parameter on the create le or override commands has been exceeded. If the WAITRCD time is exceeded without the lock being released, an exception is returned to your program and a message is sent to your job stating the le, member, relative record number, and the job which has the lock. If the job

180

OS/400 DB2 for AS/400 Database Programming V4R3

that is reading records is not running under a commitment control level of *ALL or *CS, the job is able to read a record that is locked for update. If the le you are updating has an update trigger associated with it, the trigger program is called before or after updating the record. See Chapter 17. Triggers for detailed information on trigger programs. If the les being updated are associated with referential constraints, the update operation can be affected. See Chapter 16. Referential Integrity for detailed information on referential constraints.

Adding Database Records

The write operation is used to add a new record to a physical database le member. (The WRITE statement in the RPG/400 language and the WRITE statement in the COBOL/400 language are examples of this operation.) New records can be added to a physical le member or to a logical le member that is based on the physical le member. When using a multiple format logical le, a record format name must be supplied to tell the system which physical le member to add the record to. The new record is normally added at the end of the physical le member. The next available relative record number (including deleted records) is assigned to the new record. Some high-level languages allow you to write a new record over a deleted record position (for example, the WRITE statement in COBOL/400 when the le organization is dened as RELATIVE). For more information about writing records over deleted record positions, see your high-level language guide. If the physical le to which records are added reuses deleted records, the system tries to insert the records into slots that held deleted records. Before you create or change a le to reuse deleted records, you should review the restrictions and tips for use to determine whether the le is a candidate for reuse of deleted record space. For more information on reusing deleted record space, see Reusing Deleted Records on page 99. If you are adding new records to a le member that has a keyed access path, the new record appears in the keyed sequence access path immediately at the location dened by the record key. If you are adding records to a logical member that contains select/omit values, the omit values can prevent the new record from appearing in the members access path. If the le to which you are adding a record has an insert trigger associated with it, the trigger program is called before or after inserting the record. See Chapter 17. Triggers for detailed information on trigger programs. If the les you are adding to are associated with referential constraints, record insertion can be affected. See Chapter 16. Referential Integrity for detailed information on referential constraints. The SIZE parameter on the Create Physical File (CRTPF) and Create Source Physical File (CRTSRCPF) commands determines how many records can be added to a physical le member.

Chapter 7. Basic Database File Operations

181

Identifying Which Record Format to Add in a File with Multiple Formats

If your application uses a le name instead of a record format name for records to be added to the database, and if the le used is a logical le with more than one record format, you need to write a format selector program to determine where a record should be placed in the database. A format selector can be a CL program or a high-level language program. A format selector program must be used if all of the following are true: v The logical le is not a join and not a view logical le. v The logical le is based on multiple physical les. v The program uses a le name instead of a record format name on the add operation. If you do not write a format selector program for this situation, your program ends with an error when it tries to add a record to the database. Note: A format selector program cannot be used to select a member if a le has multiple members; it can only select a record format. When an application program wants to add a record to the database le, the system calls the format selector program. The format selector program examines the record and species the record format to be used. The system then adds the record to the database le using the specied record format name.
Application Program Logical Format File Selector Program Physical File Physical File

The following example shows the programming statements for a format selector program written in the RPG/400 language:
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments+++... +++* C *ENTRY PLIST C PARM RECORD 80 C* The length of field RECORD must equal the length of C* the longest record expected.

182

OS/400 DB2 for AS/400 Database Programming V4R3

C C C C C C C

BYTE

PARM MOVELRECORD IFEQ 'A' MOVEL'HDR' ELSE MOVEL'DTL' END

FORMAT 10 BYTE 1 FORMAT FORMAT

The format selector receives the record in the rst parameter; therefore, this eld must be declared to be the length of the longest record expected by the format selector. The format selector can access any portion of the record to determine the record format name. In this example, the format selector checks the rst character in the record for the character A. If the rst character is A, the format selector moves the record format name HDR into the second parameter (FORMAT). If the character is not A, the format selector moves the record format name DTL into the second parameter. The format selector uses the second parameter, which is a 10-character eld, to pass the record format name to the system. When the system knows the name of the record format, it adds the record to the database. You do not need a format selector if: v You are doing updates only. For updates, your program already retrieved the record, and the system knows which physical le the record came from. v Your application program species the record format name instead of a le name for an add or delete operation. v All the records used by your application program are contained in one physical le. To create the format selector, you use the create program command for the language in which you wrote the program. You cannot specify USRPRF(*OWNER) on the create command. The format selector must run under the users user prole not the owners user prole. In addition, for security and integrity and because performance would be severely affected, you must not have any calls or input/output operations within the format selector. The name of the format selector is specied on the FMTSLR parameter of the Create Logical File (CRTLF), Change Logical File (CHGLF), or Override with Database File (OVRDBF) command. The format selector program does not have to exist when the le is created, but it must exist when the application program is run.

Using the Force-End-Of-Data Operation

The force-end-of-data (FEOD) operation allows you to force all changes to a le made by your program to auxiliary storage. Normally, the system determines when to force changes to auxiliary storage. However, you can use the FEOD operation to ensure that all changes are forced to auxiliary storage. The force-end-of-data (FEOD) operation also allows you to position to either the beginning or the end of a le if the le is open for input operations. *START sets the beginning or starting position in the database le member currently open to just before the rst record in the member (the rst sequential read operation reads the rst record in the current member). If MBR(*ALL) processing is in effect for the
Chapter 7. Basic Database File Operations

183

override with Database File (OVRDBF) command, a read previous operation gets the last record in the previous member. If a read previous operation is done and the previous member does not exist, the end of le message (CPF5001) is sent. *END sets the position in the database le member currently open to just after the last record in the member (a read previous operation reads the last record in the current member). If MBR(*ALL) processing is in effect for the Override with Database File (OVRDBF) command, a read next operation gets the rst record in the next member. If a read next operation is done and the next member does not exist, the end of le message (CPF5001) occurs. If the le has a delete trigger, the force-end-of-data operation is not allowed. See Chapter 17. Triggers for detailed information on triggers. If the le is part of a referential parent relationship, the FEOD operation will not be allowed. See Chapter 16. Referential Integrity for detailed information on referential constraints. See your high-level language guide for more information about the FEOD operation (some high-level languages do not support the FEOD operation).

Deleting Database Records

The delete operation allows you to delete an existing database record. (The DELET statement in the RPG/400 language and the DELETE statement in the COBOL/400 language are examples of this operation.) To delete a database record, the record must rst be read and locked. The record is locked by specifying the update option on any of the read operations listed under Reading Database Records Using an Arrival Sequence Access Path on page 174 or Reading Database Records Using a Keyed Sequence Access Path on page 175. The rules for locking records for deletion and identifying which record to delete are the same as for update operations. Note: Some high-level languages do not require that you read the record rst. These languages allow you to simply specify which record you want deleted on the delete statement. For example, the RPG/400 language allows you to delete a record without rst reading it. When a database record is deleted, the physical record is marked as deleted. This is true even if the delete operation is done through a logical le. A deleted record cannot be read. The record is removed from all keyed sequence access paths that contain the record. The relative record number of the deleted record remains the same. All other relative record numbers within the physical le member do not change. The space used by the deleted record remains in the le, but it is not reused until: v The Reorganize Physical File Member (RGZPFM) command is run to compress and free these spaces in the le member. See Reorganizing Data in Physical File Members on page 195 for more information about this command. v Your program writes a record to the le by relative record number and the relative record number used is the same as that of the deleted record. Note: The system tries to reuse deleted record space automatically if the le has the reuse deleted record space attribute specied. For more information, see Reusing Deleted Records on page 99.

184

OS/400 DB2 for AS/400 Database Programming V4R3

The system does not allow you to retrieve the data for a deleted record. You can, however, write a new record to the position (relative record number) associated with a deleted record. The write operation replaces the deleted record with a new record. See your high-level language guide for more details about how to write a record to a specic position (relative record number) in the le. To write a record to the relative record number of a deleted record, that relative record number must exist in the physical le member. You can delete a record in the le using the delete operation in your high-level language. You can also delete records in your le using the Initialize Physical File Member (INZPFM) command. The INZPFM command can initialize the entire physical le member to deleted records. For more information about the INZPFM command, see Initializing Data in a Physical File Member on page 194. If the le from which you are deleting has a delete trigger associated with it, the trigger program is called before or after deleting the record. See Chapter 17. Triggers for detailed information on triggers. If the le is part of a referential constraint relationship, record deletion may be affected. See Chapter 16. Referential Integrity for detailed information on referential constraints.

Chapter 7. Basic Database File Operations

185

186

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 8. Closing a Database File

When your program completes processing a database le member, it should close the le. Closing a database le disconnects your program from the le. The close operation releases all record locks and releases all le member locks, forces all changes made through the open data path (ODP) to auxiliary storage, then destroys the ODP. (When a shared le is closed but the ODP remains open, the functions differ. For more information about shared les, see Sharing Database Files in the Same Job or Activation Group on page 104.) The ways you can close a database le in a program include: v High-level language close statements v Close File (CLOF) command v Reclaim Resources (RCLRSC) command Most high-level languages allow you to specify that you want to close your database les. For more information about how to close a database le in a high-level language program, see your high-level language guide. You can use the Close File (CLOF) command to close database les that were opened using either the Open Database File (OPNDBF) or Open Query File (OPNQRYF) commands. You can also close database les by running the Reclaim Resources (RCLRSC) command. The RCLRSC command releases all locks (except, under commitment control, locks on records that were changed but not yet committed), forces all changes to auxiliary storage, then destroys the open data path for that le. You can use the RCLRSC command to allow a calling program to close a called programs les. (For example, if the called program returns to the calling program without closing its les, the calling program can then close the called programs les.) However, the normal way of closing les in a program is with the high-level language close operation or through the Close File (CLOF) command. For more information on resource reclamation in the integrated language environment see the ILE Concepts book. If a job ends normally (for example, a user signs off) and all the les associated with that job were not closed, the system automatically closes all the remaining open les associated with that job, forces all changes to auxiliary storage, and releases all record locks for those les. If a job ends abnormally, the system also closes all les associated with that job, releases all record locks for those les, and forces all changes to auxiliary storage.

Copyright IBM Corp. 1997, 1998

187

188

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 9. Handling Database File Errors in a Program

Error conditions detected during processing of a database le cause messages to be sent to the program message queue for the program processing the le or cause an inquiry message to be sent to the system operator message queue. In addition, le errors and diagnostic information generally appear to your program as return codes and status information in the le feedback area. (For example, the COBOL/400 language sets a return code in the le status eld, if it is dened in the program.) For more information about handling le errors in your program, see your high-level language guide. If your programming language allows you to monitor for error messages, you can choose which ones you wish to monitor for. The following messages are a small sample of the error messages you can monitor (see your high-level language guide and the CL Reference (Abridged) manual for a complete list of errors and messages you can monitor):
Message Identier CPF5001 CPF5006 CPF5007 CPF5018 CPF5025 CPF5026 CPF5027 CPF5028 CPF5029 CPF502B CPF502D CPF5030 CPF5031 CPF5032 CPF5033 CPF5034 CPF503A CPF5040 CPF5072 CPF5079 CPF5084 CPF5085 CPF5090 CPF5097 Description End of le reached Record not found Record deleted Maximum le size reached Read attempted past *START or *END Duplicate key Record in use by another job Record key changed Data mapping error Error in trigger program Referential constraint violation Partial damage on member Maximum number of record locks exceeded Record already allocated to job Select/omit error Duplicate key in another members access path Referential constraint violation Omitted record not retrieved Join value in member changed Commitment control resource limit exceeded Duplicate key for uncommitted key Duplicate key for uncommitted key in another access path Unique access path problem prevents access to member Key mapping error

Note: To display the full description of these messages, use the Display Message Description (DSPMSGD) command. If you do not monitor for any of these messages, the system handles the error. The system also sets the appropriate error return code in the program. Depending on the error, the system can end the job or send a message to the operator requesting further action.

Copyright IBM Corp. 1997, 1998

189

If a message is sent to your program while processing a database le member, the position in the le is not lost. It remains at the record it was positioned to before the message was sent, except: v After an end-of-le condition is reached and a message is sent to the program, the le is positioned at *START or *END. v After a conversion mapping message on a read operation, the le is positioned to the record containing the data that caused the message.

190

OS/400 DB2 for AS/400 Database Programming V4R3

Part 3. Managing Database Files

The chapters in this part contain information on managing database les: v Adding new members v Changing attributes of existing members v Renaming members v Removing members from a database le The chapters also contain information on member operations unique to physical les: v Initializing data v Clearing data v Reorganizing data v Displaying data This section also contains information on: v Changing database le descriptions and attributes (including the effects of changing elds in le descriptions) v Changing physical le descriptions and attributes v Changing logical le descriptions and attributes v Using database attributes and cross reference information It covers displaying information about database les such as: v Attributes Constraints Triggers v v v v Descriptions of elds Relationships between the elds Files used by programs System cross reference les

v How to write a command output directly to a database le Also included is information to help you plan for recovery of your database les in the event of a system failure: v Saving and restoring v Journaling v Using auxiliary storage v Using commitment control This section also has information on access path recovery that includes rebuilding and journaling access paths. A section on source les discusses source le concepts and reasons you would use a source le. Information on how to set up a source le, how to enter data into a source le, and ways to use a source le to create another object on the system is included.

Copyright IBM Corp. 1997, 1998

191

192

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 10. Managing Database Members

Before you perform any input or output operations on a le, the le must have at least one member. As a general rule, database les have only one member, the one created when the le is created. The name of this member is the same as the le name, unless you give it a different name. Because most operations on database les assume that the member being used is the rst member in the le, and because most les only have one member, you do not normally have to be concerned with, or specify, member names. If a le contains more than one member, each member serves as a subset of the data in the le. This allows you to classify data easier. For example, you dene an accounts receivable le. You decide that you want to keep data for a year in that le, but you frequently want to process data just one month at a time. For example, you create a physical le with 12 members, one named for each month. Then, you process each months data separately (by individual member). You can also process several or all members together.

Member Operations Common to All Database Files

The system supplies a way for you to: v Add new members to an existing le. v Change some attributes for an existing member (for example, the text describing the member) without having to re-create the member. v Rename a member. v Remove the member from the le. The following section discusses these operations.

Adding Members to Files

You can add members to les in any of these ways: v Automatically. When a le is created using the Create Physical File (CRTPF) or Create Logical File (CRTLF) commands, the default is to automatically add a member (with the same name as the le) to the newly created le. (The default for the Create Source Physical File (CRTSRCPF) command is not to add a member to the newly created le.) You can specify a different member name using the MBR parameter on the create database le commands. If you do not want a member added when the le is created, specify *NONE on the MBR parameter. v Specically. After the le is created, you can add a member using the Add Physical File Member (ADDPFM) or Add Logical File Member (ADDLFM) commands. v Copy File (CPYF) command. If the member you are copying does not exist in the le being copied to, the member is added to the le by the CPYF command.

Changing Member Attributes

You can use the Change Physical File Member (CHGPFM) or Change Logical File Member (CHGLFM) command to change certain attributes of a physical or a
Copyright IBM Corp. 1997, 1998

193

logical le member. For a physical le member, you can change the following parameters: SRCTYPE (the members source type), EXPDATE (the members expiration date), SHARE (whether the member can be shared within a job), and TEXT (the text description of the member). For a logical le member you can change the SHARE and TEXT parameters. Note: You can use the Change Physical File (CHGPF) and Change Logical File (CHGLF) commands to change many other le attributes. For example, to change the maximum size allowed for each member in the le, you would use the SIZE parameter on the CHGPF command.

Renaming Members
The Rename Member (RNMM) command changes the name of an existing member in a physical or logical le. The le name is not changed.

Removing Members from Files

The Remove Member (RMVM) command is used to remove the member and its contents. Both the member data and the member itself are removed. After the member is removed, it can no longer be used by the system. This is different from just clearing or deleting the data from the member. If the member still exists, programs can continue to use (for example, add data to) the member.

Physical File Member Operations

The following section describes member operations that are unique to physical le members. Those operations include initializing data, clearing data, reorganizing data, and displaying data in a physical le member. If the le member being operated on is associated with referential constraints, the operation can be affected. See Chapter 16. Referential Integrity for detailed information on referential constraints.

Initializing Data in a Physical File Member

To use relative record processing in a program, the database le must contain a number of record positions equal to the highest relative record number used in the program. Programs using relative-record-number processing sometimes require that these records be initialized. You can use the Initialize Physical File Member (INZPFM) command to initialize members with one of two types of records: v Default records v Deleted records You specify which type of record you want using the RECORDS parameter on the Initialize Physical File Member (INZPFM) command. If you initialize records using default records, the elds in each new record are initialized to the default eld values dened when the le was created. If no default eld value was dened, then numeric elds are lled with zeros and character elds are lled with blanks.

194

OS/400 DB2 for AS/400 Database Programming V4R3

Variable-length character elds have a zero-length default value. The default value for null-capable elds is the null value. The default value for dates, times, and timestamps is the current date, time, or timestamp if no default value is dened. Program-described les have a default value of all blanks. Note: You can initialize one default record if the UNIQUE keyword is specied in DDS for the physical le member or any associated logical le members. Otherwise, you would create a series of duplicate key records. If the records are initialized to the default records, you can read a record by relative record number and change the data. If the records were initialized to deleted records, you can change the data by adding a record using a relative record number of one of the deleted records. (You cannot add a record using a relative record number that was not deleted.) Deleted records cannot be read; they only hold a place in the member. A deleted record can be changed by writing a new record over the deleted record. Refer to Deleting Database Records on page 184 for more information about processing deleted records.

Clearing Data from Physical File Members

The Clear Physical File Member (CLRPFM) command is used to remove the data from a physical le member. After the clear operation is complete, the member description remains, but the data is gone.

Reorganizing Data in Physical File Members

You can use the Reorganize Physical File Member (RGZPFM) command to: v Remove deleted records to make the space occupied by them available for more records. v Reorganize the records of a le in the order in which you normally access them sequentially, thereby minimizing the time required to retrieve records. This is done using the KEYFILE parameter. This may be advantageous for les that are primarily accessed in an order other than arrival sequence. A member can be reorganized using either of the following: Key elds of the physical le Key elds of a logical le based on the physical le v Reorganize a source le member, insert new source sequence numbers, and reset the source date elds (using the SRCOPT and SRCSEQ parameters on the Reorganize Physical File Member command). v Reclaim space in the variable portion of the le that was previously used by variable-length elds in the physical le format and that has now become fragmented. For example, the following Reorganize Physical File Member (RGZPFM) command reorganizes the rst member of a physical le using an access path from a logical le:
RGZPFM FILE(DSTPRODLB/ORDHDRP) KEYFILE(DSTPRODLB/ORDFILL ORDFILL)

Chapter 10. Managing Database Members

195

The physical le ORDHDRP has an arrival sequence access path. It was reorganized using the access path in the logical le ORDFILL. Assume the key eld is the Order eld. The following illustrates how the records were arranged. The following is an example of the original ORDHDRP le. Note that record 3 was deleted before the RGZPFM command was run:
Relative Record Number 1 2 3 4 Cust 41394 28674 deleted 56325 Order 41882 32133 record 38694 Ordate. . . 072480. . . 060280. . . 062780. . .

The following example shows the ORDHDRP le reorganized using the Order eld as the key eld in ascending sequence:
Relative Record Number 1 2 3 Cust 28674 56325 41394 Order 32133 38694 41882 Ordate. . . 060280. . . 062780. . . 072480. . .

Notes: 1. If a le with an arrival sequence access path is reorganized using a keyed sequence access path, the arrival sequence access path is changed. That is, the records in the le are physically placed in the order of the keyed sequence access path used. By reorganizing the data into a physical sequence that closely matches the keyed access path you are using, you can improve the performance of processing the data sequentially. 2. Reorganizing a le compresses deleted records, which changes subsequent relative record numbers. 3. Because access paths with either the FIFO or LIFO DDS keyword specied depend on the physical sequence of records in the physical le, the sequence of the records with duplicate key elds may change after reorganizing a physical le using a keyed sequence access path. Also, because access paths with the FCFO DDS keyword specied are ordered as FIFO, when a reorganization is done, the sequence of the records with duplicate key elds may also change. 4. If you cancel the RGZPFM command, all the access paths over the physical le member may have to be rebuilt. If one of the following conditions occur and the Reorganize Physical File Member (RGZPFM) command is running, the records may not be reorganized: v The system ends abnormally. v The job containing the RGZPFM command is ended with an *IMMED option. v The subsystem in which the RGZPFM command is running ends with an *IMMED option. v The system stops with an *IMMED option. The status of the member being reorganized depends on how much the system was able to do before the reorganization was ended and what you specied in the SRCOPT parameter. If the SRCOPT parameter was not specied, the member is either completely reorganized or not reorganized at all. You should display the

196

OS/400 DB2 for AS/400 Database Programming V4R3

contents of the le, using the Display Physical File Member (DSPPFM) command, to determine if it was reorganized. If the member was not reorganized, issue the Reorganize Physical File Member (RGZPFM) command again. If the SRCOPT parameter was specied, any of the following could have happened to the member: v It was completely reorganized. A completion message is sent to your job log indicating the reorganize operation was completely successful. v It was not reorganized at all. A message is sent to your job log indicating that the reorganize operation was not successful. If this occurs, issue the Reorganize Physical File Member (RGZPFM) command again. v It was reorganized, but only some of the sequence numbers were changed. A completion message is sent to your job log indicating that the member was reorganized, but all the sequence numbers were not changed. If this occurs, issue the RGZPFM command again with KEYFILE(*NONE) specied. To reduce the number of deleted records that exist in a physical le member, the le can be created or changed to reuse deleted record space. For more information, see Reusing Deleted Records on page 99.

Displaying Records in a Physical File Member

The Display Physical File Member (DSPPFM) command can be used to display the data in the physical database le members by arrival sequence. The command can be used for: v Problem analysis v Debugging v Record inquiry You can display source les or data les, regardless if they are keyed or arrival sequence. Records are displayed in arrival sequence, even if the le is a keyed le. You can page through the le, locate a particular record by record number, or shift the display to the right or left to see other parts of the records. You can also press a function key to show either character data or hexadecimal data on the display. If you have Query installed, you can use the Start Query (STRQRY) command to select and display records, too. If you have the SQL language installed, you can use the Start SQL (STRSQL) command to interactively select and display records.

Chapter 10. Managing Database Members

197

198

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 11. Changing Database File Descriptions and Attributes

This chapter describes the things to consider when planning to change the description or attributes of a database le.

Effect of Changing Fields in a File Description

When a program that uses externally described data is compiled, the compiler copies the le descriptions of the les into the compiled program. When you run the program, the system can verify that the record formats the program was compiled with are the same as the record formats currently dened for the le. The default is to do level checking. The system assigns a unique level identier for each record format when the le it is associated with is created. The system uses the information in the record format description to determine the level identier. This information includes the total length of the record format, the record format name, the number and order of elds dened, the data type, the size of the elds, the eld names, and the number of decimal positions in the eld. Changes to this information in a record format cause the level identier to change. The following DDS information has no effect on the level identier and, therefore, can be changed without recompiling the program that uses the le: v TEXT keyword v COLHDG keyword v CHECK keyword v EDTCDE keyword v v v v v EDTWRD keyword REF keyword REFFLD keyword CMP, RANGE, and VALUES keywords TRNTBL keyword

v REFSHIFT keyword v DFT keyword v CCSID keyword v ALWNULL keyword v v v v Join specications and join keywords Key elds Access path keywords Select/omit elds

Keep in mind that even though changing key elds or select/omit elds will not cause a level check, the change may cause unexpected results in programs using the new access path. For example, changing the key eld from the customer number to the customer name changes the order in which the records are retrieved, and may cause unexpected problems in the programs processing the le.

Copyright IBM Corp. 1997, 1998

199

If level checking is specied (or defaulted to), the level identier of the le to be used is compared to the level identier of the le in your program when the le is opened. If the identiers differ, a message is sent to the program to identify the changed condition and the changes may affect your program. You can simply compile your program again so that the changes are included. An alternative is to display the le description to determine if the changes affect your program. You can use the Display File Field Description (DSPFFD) command to display the description or, if you have SEU, you can display the source le containing the DDS for the le. The format level identier dened in the le can be displayed by the Display File Description (DSPFD) command. When you are displaying the level identier, remember that the record format identier is compared, rather than the le identier. Not every change in a le necessarily affects your program. For example, if you add a eld to the end of a le and your program does not use the new eld, you do not have to recompile your program. If the changes do not affect your program, you can use the Change Physical File (CHGPF) or the Change Logical File (CHGLF) commands with LVLCHK(*NO) specied to turn off level checking for the le, or you can enter an Override with Database File (OVRDBF) command with LVLCHK(*NO) specied so that you can run your program without level checking. Keep in mind that level checking is the preferred method of operating. The use of LVLCHK(*YES) is a good database integrity practice. The results produced by LVLCHK(*NO) cannot always be predicted.

Changing a Physical File Description and Attributes

Sometimes, when you make a change to a physical le description and then re-create the le, the level identier can change. For example, the level identier will change if you add a eld to the le description, or change the length of an existing eld. If the level identier changes, you can compile the programs again that use the physical le. After the programs are recompiled, they will use the new level check identier. You can avoid compiling again by creating a logical le that presents data to your programs in the original record format of the physical le. Using this approach, the logical le has the same level check identier as the physical le before the change. For example, you decide to add a eld to a physical le record format. You can avoid compiling your program again by doing the following: 1. Change the DDS and create a new physical le (FILEB in LIBA) to include the new eld:
CRTPF FILE(LIBA/FILEB) MBR(*NONE)...

FILEB does not have a member. (The old le FILEA is in library LIBA and has one member MBRA.) 2. Copy the member of the old physical le to the new physical le:
CPYF FROMFILE(LIBA/FILEA) TOFILE(LIBA/FILEB) FROMMBR(*ALL) TOMBR(*FROMMBR) MBROPT(*ADD) FMTOPT(*MAP)

200

OS/400 DB2 for AS/400 Database Programming V4R3

The member in the new physical le is automatically named the same as the member in the old physical le because FROMMBR(*ALL) and TOMBR(*FROMMBR) are specied. The FMTOPT parameter species to copy (*MAP) the data in the elds by eld name. 3. Describe a new logical le (FILEC) that looks like the original physical le (the logical le record format does not include the new physical le eld). Specify FILEB for the PFILE keyword. (When a level check is done, the level identier in the logical le and the level identier in the program match because FILEA and FILEC have the same format.) 4. Create the new logical le:
CRTLF FILE(LIBA/FILEC)...

5. You can now do one of the following: a. Use an Override with Database File (OVRDBF) command in the appropriate jobs to override the old physical le referred to in the program with the logical le (the OVRDBF command parameters are described in more detail in Chapter 5. Run Time Considerations).
OVRDBF FILE(FILEA) TOFILE(LIBA/FILEC)

b. Delete the old physical le and rename the logical le to the name of the old physical le so the le name in the program does not have to be overridden.
DLTF FILE(LIBA/FILEA) RNMOBJ OBJ(LIBA/FILEC) OBJTYPE(*FILE) NEWOBJ(FILEA)

The following illustrates the relationship of the record formats used in the three les:
FILEA (old physical file) FLDA FLDB FLDC FLDD FILEB (new physical file) FLDB1 FLDB1 was added to the record format. FILEC (logical file) FLDA FLDB FLDC FLDD FILEC shares FLDB1 is not used in the record the record format for format of the logical file. FILEA.

When you make changes to a physical le that cause you to create the le again, all logical les referring to it must rst be deleted before you can delete and create the new physical le. After the physical le is re-created, you can re-create or restore the logical les referring to it. The following examples show two ways to do this.

Chapter 11. Changing Database File Descriptions and Attributes

201

Example 1
Create a new physical le with the same name in a different library 1. Create a new physical le with a different record format in a library different from the library the old physical le is in. The name of new le should be the same as the name of the old le. (The old physical le FILEPFC is in library LIBB and has two members, MBRC1 and MBRC2.)
CRTPF FILE(NEWLIB/FILEPFC) MAXMBRS(2)...

2. Copy the members of the old physical le to the new physical le. The members in the new physical le are automatically named the same as the members in the old physical le because TOMBR(*FROMMBR) and FROMMBR(*ALL) are specied.
CPYF FROMFILE(LIBB/FILEPFC) TOFILE(NEWLIB/FILEPFC) FROMMBR(*ALL) TOMBR(*FROMMBR) FMTOPT(*MAP *DROP) MBROPT(*ADD)

3. Describe and create a new logical le in a library different from the library the old logical le is in. The name of the new logical le should be the same as the old logical le name. You can use the FORMAT keyword to use the same record formats as in the current logical le if no changes need to be made to the record formats. You can also use the Create Duplicate Object (CRTDUPOBJ) command to create another logical le from the old logical le FILELFC in library LIBB.
CRTLF FILE(NEWLIB/FILELFC)

4. Delete the old logical and physical les.

DLTF FILE(LIBB/FILELFC) DLTF FILE(LIBB/FILEPFC)

5. Move the newly created les to the original library by using the following commands:
MOVOBJ OBJ(NEWLIB/FILELFC) OBJTYPE(*FILE) TOLIB(LIBB) MOVOBJ OBJ(NEWLIB/FILEPFC) OBJTYPE(*FILE) TOLIB(LIBB)

Example 2
Creating new versions of les in the same libraries 1. Create a new physical le with a different record format in the same library the old physical le is in. The names of the les should be different. (The old physical le FILEPFA is in library LIBA and has two members MBRA1 and MBRA2.)
CRTPF FILE(LIBA/FILEPFB) MAXMBRS(2)...

2. Copy the members of the old physical le to the new physical le.
CPYF FROMFILE(LIBA/FILEPFA) TOFILE(LIBA/FILEPFB) FROMMBR(*ALL) TOMBR(*FROMMBR) FMTOPT(*MAP *DROP) MBROPT(*REPLACE)

3. Create a new logical le in the same library as the old logical le is in. The names of the old and new les should be different. (You can use the FORMAT keyword to use the same record formats as are in the current logical le if no changes need be made to the record formats.) The PFILE keyword must refer to the new physical le created in step 1. The old logical le FILELFA is in library LIBA.
CRTLF FILE(LIBA/FILELFB)

4. Delete the old logical and physical les.

DLTF FILE(LIBA/FILELFA) DLTF FILE(LIBA/FILEPFA)

202

OS/400 DB2 for AS/400 Database Programming V4R3

5. Rename the new logical le to the name of the old logical le. (If you also decide to rename the physical le, be sure to change the DDS for logical le so that the PFILE keyword refers to the new physical le name.)
RNMOBJ(LIBA/FILELFB) OBJTYPE(*FILE) NEWOBJ(FILELFA)

6. If the logical le member should be renamed, and assuming the default was used on the Create Logical File (CRTLF) command, issue the following command:
RNMM FILE(LIBA/FILELFA) MBR(FILELFB) NEWMBR(FILELFA)

You can use the Change Physical File (CHGPF) command to change some of the attributes of a physical le and its members. For information on these parameters, see the Change Physical File (CHGPF) command in the CL Reference (Abridged) .

Changing a Logical File Description and Attributes

As a general rule, when you make changes to a logical le that will cause a change to the level identier (for example, adding a new eld, deleting a eld, or changing the length of a eld), it is strongly recommended that you recompile the programs that use the logical le. Sometimes you can make changes to a le that change the level identier and which do not require you to recompile your program (for example, adding a eld that will not be used by your program to the end of the le). However, in those situations you will be forced to turn off level checking to run your program using the changed le. That is not the preferred method of operating. It increases the chances of incorrect data in the future. To avoid recompiling, you can keep the current logical le (unchanged) and create a new logical le with the added eld. Your program refers to the old le, which still exists. You can use the Change Logical File (CHGLF) command to change most of the attributes of a logical le and its members that were specied on the Create Logical File (CRTLF) command.

Chapter 11. Changing Database File Descriptions and Attributes

203

204

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 12. Using Database Attribute and Cross-Reference Information

The AS/400 integrated database provides le attribute and cross-reference information. Some of the cross-reference information includes: v The les used in a program v The les that depend on other les for data or access paths v File attributes v The elds dened for a le v Constraints associated with a le v Key elds for a le Each of the commands described in the following sections can present information on a display, a printout, or write the cross-reference information to a database le that, in turn, can be used by a program or utility (for example, Query) for analysis. For more information about writing the output to a database le, see Writing the Output from a Command Directly to a Database File on page 209. You can retrieve information about a member of a database le for use in your applications with the Retrieve Member Description (RTVMBRD) command. See the section on Retrieving Member Description Information in the CL Programming for an example of how the RTVMBRD command is used in a CL program to retrieve the description of a specic member.

Displaying Information about Database Files Displaying Attributes for a File

You can use the Display File Description (DSPFD) command to display the le attributes for database les and device les. The information can be displayed, printed, or written to a database output le (OUTFILE). The information supplied by this command includes (parameter values given in parentheses): v v v v v Basic attributes (*BASATR) File attributes (*ATR) Access path specications (*ACCPTH, logical and physical les only) Select/omit specications (*SELECT, logical les only) Join logical le specications (*JOIN, join logical les only)

v Alternative collating sequence specications (*SEQ, physical and logical les only) v Record format specications (*RCDFMT) v Member attributes (*MBR, physical and logical les only) v Spooling attributes (*SPOOL, printer and diskette les only) v Member lists (*MBRLIST, physical and logical les only) v File constraints (*CST) v Triggers (*TRG)
Copyright IBM Corp. 1997, 1998

205

Displaying the Descriptions of the Fields in a File

You can use the Display File Field Description (DSPFFD) command to display eld information for both database and device les. The information can be displayed, printed, or written to a database output le (OUTFILE).

Displaying the Relationships between Files on the System

You can use the Display Database Relations (DSPDBR) command to display the following information about the organization of your database: v A list of database les (physical and logical) that use a specic record format. v A list of database les (physical and logical) that depend on the specied le for data sharing. v A list of members (physical and logical) that depend on the specied member for sharing data or sharing an access path. v A list of physical les that are dependent les in a referential constraint relationship with this le. This information can be displayed, printed, or written to a database output le (OUTFILE). For example, to display a list of all database les associated with physical le ORDHDRP, with the record format ORDHDR, type the following DSPDBR command:
DSPDBR FILE(DSTPRODLB/ORDHDRP) RCDFMT(ORDHDR)

Note: See the DSPDBR command description in the CL Reference (Abridged) for details of this display. This display presents header information when a record format name is specied on the RCDFMT parameter, and presents information about which les are using the specied record format. If a member name is specied on the MBR parameter of the DSPDBR command, the dependent members are shown. If the Display Database Relations (DSPDBR) command is specied with the default MBR(*NONE) parameter value, the dependent data les are shown. To display the shared access paths, you must specify a member name. The Display Database Relations (DSPDBR) command output identies the type of sharing involved. If the results of the command are displayed, the name of the type of sharing is displayed. If the results of the command are written to a database le, the code for the type of sharing (shown below) is placed in the WHTYPE eld in the records of the output le.
Type Constraint Code C Description The physical le is dependent on the data in another physical le to which it is associated via a constraint. The le or member is dependent on the data in a member of another le.

Data

206

OS/400 DB2 for AS/400 Database Programming V4R3

Type Access path sharing Access path owner

Code I O

SQL View

Description The le member is sharing an access path. If an access path is shared, one of the le members is considered the owner. The owner of the access path is charged with the storage used for the access path. If the member displayed is designated the owner, one or more le members are designated with an I for access path sharing. The SQL view or member is dependent upon another SQL view.

Displaying the Files Used by Programs

You can use the Display Program Reference (DSPPGMREF) command to determine which les, data areas, and other programs are used by a program. This information is available for compiled programs only. The information can be displayed, printed, or written to a database output le (OUTFILE). When a program is created, the information about certain objects used in the program is stored. This information is then available for use with the Display Program References (DSPPGMREF) command. The following chart shows the objects for which the high-level languages and utilities save information:
Language or Utility BASIC C/400 Language CL COBOL/400 Language CSP DFU FORTRAN/400* Language Pascal PL/I RPG/400 Language SQL Language Files Yes No Yes Yes Yes Yes No No Yes Yes Yes Programs Yes No Yes Yes Yes N/A No No Yes Yes N/A Data Areas No N/A Yes No No N/A N/A N/A N/A Yes N/A See Notes 1 2 3 4

3 5

Chapter 12. Using Database Attribute and Cross-Reference Information

207

Language or Utility : Notes:

Files

Programs

Data Areas

See Notes

1. Externally described le references, programs, and data areas are stored. 2. All system commands that refer to les, programs, or data areas specify in the command denition that the information should be stored when the command is compiled in a CL program. If a variable is used, the name of the variable is used as the object name (for example, &FILE); If an expression is used, the name of the object is stored as *EXPR. User-dened commands can also store the information for les, programs, or data areas specied on the command. See the description of the FILE, PGM, and DTAARA parameters on the PARM or ELEM command statements in the CL Programming book. 3. The program name is stored only when a literal is used for the program name (this is a static call, for example, CALL 'PGM1'), not when a COBOL/400 identier is used for the program name (this is a dynamic call, for example, CALL PGM1). 4. CSP programs also save information for an object of type *MSGF, *CSPMAP, and *CSPTBL. 5. The use of the local data area is not stored.

The stored le information contains an entry (a number) for the type of use. In the database le output of the Display Program References (DSPPGMREF) command (built when using the OUTFILE parameter), this is specied as: Code 1 2 3 4 8 Meaning Input Output Input and Output Update Unspecied

Combinations of codes are also used. For example, a le coded as a 7 would be used for input, output, and update.

Displaying the System Cross-Reference Files

The system manages eight database les that contain: v Basic database le attribute information (QSYS/QADBXREF) v Cross-reference information (QSYS/QADBFDEP) about all the database les on the system (except those database les that are in the QTEMP library) v Database le eld information (QSYS/QADBIFLD) v Database le key eld information (QSYS/QADBKFLD) v Referential constraint le information (QSYS/QADBFCST) v Referential constraint eld information (QSYS/QADBCCST) v SQL package information (QSYS/QADBPKG) v Remote database directory information (QSYS/QADBXRDBD) You can use these les to determine basic attribute and database le requirements. To display the elds contained in these les, use the Display File Field Description (DSPFFD) command.

208

OS/400 DB2 for AS/400 Database Programming V4R3

Note: The authority to use these les is restricted to the security officer. However, all users have authority to view the data by using one of (or the only) logical le built over each le. The authorities for these les cannot be changed because they are always open.

Writing the Output from a Command Directly to a Database File

You can store the output from many CL commands in an output physical le by specifying the OUTFILE parameter on the command. You can use the output les in programs or utilities (for example, Query) for data analysis. For example, you can send the output of the Display Program References (DSPPGMREF) command to a physical le, then query that le to determine which programs use a specic le. The physical les are created for you when you specify the OUTFILE parameter on the commands. Initially, the les are created with private authority; only the owner (the person who ran the command) can use it. However, the owner can authorize other users to these les as you would for any other database le. The system supplies model les that identify the record format for each command that can specify the OUTFILE parameter. If you specify a le name on the OUTFILE parameter for a le that does not already exist, the system creates the le using the same record format as the model les. If you specify a le name for an existing output le, the system checks to see if the record format is the same record format as the model le. If the record formats do not match, the system sends a message to the job and the command does not complete. Note: You must use your own les for output les, rather than specifying the system-supplied model les on the OUTFILE parameter. See the Programming Reference Summary for a list of commands that allow output les and the names of the model les supplied for those commands. Note: All system-supplied model les are located in the QSYS library. You can display the elds contained in the record formats of the system-supplied model les using the Display File Field Descriptions (DSPFFD) command.

Example of Using a Command Output File

The following example uses the Display Program References (DSPPGMREF) command to collect information for all compiled programs in all libraries, and place the output in a database le named DBROUT:
DSPPGMREF PGM(*ALL/*ALL) OUTPUT(*OUTFILE) OUTFILE(DSTPRODLB/DBROUT)

You can use Query to process the output le. Another way to process the output le is to create a logical le to select information from the le. The following is the DDS for such a logical le. Records are selected based on the le name.

Chapter 12. Using Database Attribute and Cross-Reference Information

209

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* Logical file DBROUTL for query A A R DBROUTL PFILE(DBROUT) A S WHFNAM VALUES('ORDHDRL' 'ORDFILL') A

Output File for the Display File Description Command

The Display File Description (DSPFD) command provides unique output les, depending on the parameters specied. See the Programming Reference Summary for a list of the model les for the DSPFD command. Note: All system-supplied model les are in the QSYS library. To collect access path information about all les in the LIBA library, you could specify:
DSPFD FILE(LIBA/*ALL) TYPE(*ACCPTH) OUTFILE(LIBB/ABC) OUTPUT(*OUTFILE) +

The le ABC is created in library LIBB and is externally described with the same eld descriptions as in the system-supplied le QSYS/QAFDACCP. The ABC le then contains a record for each key eld in each le found in library LIBA that has an access path. If the Display File Description (DSPFD) command is coded as:
DSPFD FILE(LIBX/*ALL) TYPE(*ATR) OUTPUT(*OUTFILE) + FILEATR(*PF) OUTFILE(LIBB/DEF)

the le DEF is created in library LIBB and is externally described with the same eld descriptions as exist in QSYS/QAFDPHY. The DEF le then contains a record for each physical le found in library LIBX. You can display the eld names of each model le supplied by IBM using the DSPFFD command. For example, to display the eld description for the access path model le (*ACCPTH specied on the TYPE parameter), specify the following:
DSPFFD QSYS/QAFDACCP

Output Files for the Display Journal Command

See the Programming Reference Summary for a list of model output les supplied on the system that can be shown with the Display Journal (DSPJRN) command.

Output Files for the Display Problem Command

See the Programming Reference Summary for a list of model output les supplied on the system for the Display Problem (DSPPRB) command. The command provides unique output les depending on the type of record: v Basic problem data record (*BASIC). This includes problem type, status, machine type/model/serial number, product ID, contact information, and tracking data. v Point of failure, isolation, or answer FRU records (*CAUSE). Answer FRUs are used if they are available. If answer FRUs are not available, isolation FRUs are used if they are available. If answer FRUs and isolation FRUs are not available, then point of failure FRUs are used.

210

OS/400 DB2 for AS/400 Database Programming V4R3

v PTF x records (*FIX). v User-entered text (note records) (*USRTXT). v Supporting data identier records (*SPTDTA). The records in all ve output les have a problem identier so that the cause, x, user text information, and supporting data can be correlated with the basic problem data. Only one type of data can be written to a particular output le. The cause, x, user text, and supporting data output les can have multiple records for a particular problem. See the CL Reference (Abridged) for more information on the DSPPRB command.

Chapter 12. Using Database Attribute and Cross-Reference Information

211

212

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 13. Database Recovery Considerations

This chapter describes the general considerations and AS/400 facilities that enable you to recover or restore your database following any type of unexpected or undesirable event that could cause loss of data on the system. See the Backup and Recovery book for comprehensive discussion of AS/400 backup and recovery strategies, plans, and facilities.

Database Save and Restore

It is important that you save your database les and related objects periodically so that you can restore them when necessary. Database les and related objects can be saved and restored using any supported device and media or a save le. When information is saved, a copy of the information in a special format is written onto the media or to a save le. Some media can be removed and stored for future use on your system or on another AS/400 system. When information is restored, it is read from the media or a save le into storage where it can be accessed by system users. Save les are disk-resident les that can be the target of a save operation or the source of a restore operation. Save les allow unattended save operations. That is, an operator does not need to load tapes or diskettes when saving to a save le. However, it is still important to use the Save Save File Data (SAVSAVFDTA) command to periodically save the save le data on tape or diskette. The tapes or diskettes should periodically be removed from the site. Storing a copy of your save tapes or diskettes away from the system site is important to help recover from a site disaster. See the Backup and Recovery book for detailed design and programming considerations related to using the save-while-active function.

Considerations for Save and Restore

When you save a database le or related object to tape or diskette, the system updates the object description with the date and time of the save operation. When you save an object to a save le, you can prevent the system from updating the date and time of the save operation by specifying UPDHST(*NO) on the save command. When you restore an object, the system always updates the object description with the date and time of the restore operation. You can display this and other save/restore related information by using the Display Object Description (DSPOBJD) command with DETAIL(*FULL). Use the Display Save File (DSPSAVF) command to display the objects in a save le. Specify DATA(*SAVRST) on the Display Diskette (DSPDKT) or Display Tape (DSPTAP) command for a display of the objects on the media. The last save/restore date for database members can be displayed by typing:
DSPFD FILE(file-name) TYPE(*MBR)

Copyright IBM Corp. 1997, 1998

213

Database Data Recovery

The AS/400 system has integrated recovery functions to help recover data in a database le. The key functions described in this chapter are: v Journal management, for recording data changes to les v Commitment control, for synchronizing transaction recovery v Force-writing data changes to auxiliary storage v Abnormal system end recovery (see Database Recovery after an Abnormal System End on page 222)

Journal Management
Journal management allows you to record all the data changes occurring to one or more database les. You can then use the journal for recovery. You should seriously consider using journal management. If a database le is destroyed or becomes unusable and you are using journaling, you can reconstruct most of the activity for the le (see the journaling topic in the Backup and Recovery book for details). Optionally, the journal allows you to remove changes made to the le. Journaling can be started or ended very easily. It requires no additional programming or changes to existing programs. When a change is made to a le and you are using journaling, the system records the change in a journal receiver and writes the receiver to auxiliary storage before it is recorded in the le. Therefore, the journal receiver always has the latest database information. Activity for a le is journaled regardless of the type of program, user, or job that made the change, or the logical le through which the change was made. Journal entries record activity for a specic record (record added, updated or deleted), or for the le as a whole (le opened, le member saved, and so on). Each entry includes additional bytes of control information identifying the source of the activity (such as user, job, program, time, and date). For changes that affect a single record, record images are included following the control information. The image of the record after a change is made is always included. Optionally, the record image before the change is made can also be included. You control whether to journal both before and after record images or just after record images by specifying the IMAGES parameter on the Start Journal Physical File (STRJRNPF) command. Notes: 1. If a database change is an update and the updated record exactly matches the existing record, a journal entry is not deposited for the change. This applies only if the le has no variable length elds. 2. If these le or record changes are caused by a trigger program or a referential integrity constraint, the associated journal entry indicates that. See Chapter 16. Referential Integrity for more information on referential integrity and Chapter 17. Triggers for more information on triggers. All journaled database les are automatically synchronized with the journal when the system is started (IPL time). If the system ended abnormally, some database

214

OS/400 DB2 for AS/400 Database Programming V4R3

changes may be in the journal, but not yet reected in the database itself. If that is the case, the system automatically updates the database from the journal to bring the database les up to date. Journaling can make saving database les easier and faster. For example, instead of saving an entire le everyday, you can simply save the journal receiver that contains the changes to that le. You might still save the entire le on a weekly basis. This method can reduce the amount of time it takes to perform your daily save operations. The Apply Journaled Changes (APYJRNCHG) and Remove Journaled Changes (RMVJRNCHG) commands can be used to recover a damaged or unusable database le member using the journaled changes. The APYJRNCHG command applies the changes that were recorded in a journal receiver to the designated physical le member. Depending on the type of damage to the physical le and the amount of activity since the le was last saved, removing changes from the le using the RMVJRNCHG command can be easier. The Work with Journal (WRKJRN) command provides a prompted method for applying changes. The Display Journal (DSPJRN) command, can be used to convert journal entries to a database le. Such a le can be used for activity reports, audit trails, security, and program debugging. Because the journal supplies many useful functions, not the least of which is recovering data, journal management ought to be considered a key part of your recovery strategy. See the Backup and Recovery book for more information about journal management and the described commands.

Transaction Recovery through Commitment Control

Commitment control is a function that allows you to dene and process a number of changes to database les as a single unit (transaction). Commitment control is an extension of the journal function on the system that provides you additional assistance in recovering data and restarting your programs. Commitment control can ensure that complex application transactions are logically synchronized even if the job or system ends. Two-phase commitment control ensures that committable resources, such as database les, on multiple systems remain synchronized. A transaction is a group of changes that appear as a single change, such as the transfer of funds from a savings account to a checking account. Transactions can be classied as follows: v Inquiries in which no le changes occur. v Simple transactions in which one le is changed each time you press the Enter key. v Complex transactions in which two or more les are changed each time you press the Enter key. v Complex transactions in which one or more les are changed each time you press the Enter key, but these changes represent only part of a logical group of transactions. Changes made to les during transaction processing are journaled when using commitment control. If the system or job ends abnormally, journaling alone can ensure that, at most, only the very last record change is lost. However, if the system or job ends
Chapter 13. Database Recovery Considerations

215

abnormally during a complex transaction (where more than one le may be changed), the les can reect an incomplete logical transaction. For example, the job may have updated a record in le A, but before it had a chance to update a corresponding record in le B the job ended abnormally. In this case, the logical transaction consisted of two updates, but only one update completed before the job ended abnormally. Recovering a complex application requires detailed application knowledge. Programs cannot simply be restarted; for example, record changes may have to be made with an application program or data le utility to reverse the les to just before the last complex transaction began. This task becomes more complex if multiple users were accessing the les at the same time. Commitment control helps solve these problems. Under commitment control, the records used during a complex transaction are locked from other users. This ensures that other users do not use the records until the transaction is complete. At the end of the transaction, the program issues the commit operation, freeing the records. However, should the system or job end abnormally before the commit operation is performed, all record changes for that job since the last time a commit operation occurred are rolled back. Any affected records that are still locked are then unlocked. In other words, database changes are rolled back to a clean transaction boundary. The rollback operation can also occur under your control. Assume that in an order entry application, the application program runs the commit operation at the end of each order. In the middle of an order, the operator can signal the program to do a rollback operation. All le changes will be rolled back to the beginning of the order. The commit and roll back operations are available in several AS/400 programming languages including the RPG/400, COBOL/400, PL/I, SQL, and the AS/400 control language (CL). An optional feature of commitment control is the use of a notify object. The notify object is a le, data area, or message queue. When the job or system ends during a transaction, information specied by the program is automatically sent to the notify object. This information can be used by an operator or application programs to start the application from the last successful transaction boundary. Commitment control can also be used in a batch environment. Just as it provides assistance in interactive transaction recovery, commitment control can help in batch job recovery. See the Backup and Recovery book for more information about commitment control.

Force-Writing Data to Auxiliary Storage

The force-write ratio (FRCRATIO) parameter on the create le and override database le commands can be used to force data to be physically written to auxiliary storage. A force-write ratio of one causes every add, update, and delete request to be immediately written to auxiliary storage for the le in question. However, choosing this option can reduce system performance. Therefore, saving your les and journaling your les should be considered the primary methods for protecting database les.

216

OS/400 DB2 for AS/400 Database Programming V4R3

Access Path Recovery

The system ensures the integrity of an access path before you can use it. If the system determines that the access path is unusable, the system attempts to recover it. You can control when an access path will be recovered. See Controlling When Access Paths Are Rebuilt on page 218 for more information. Access path recovery can take a long time, especially if you have large access paths or many access paths to be rebuilt. You can reduce this recovery time in several ways, including: v v v v v Saving access paths Using access path journaling Controlling when access paths are rebuilt Designing les to reduce rebuild time Using system-managed access-path protection

Saving Access Paths

You can reduce the time required to recover access paths by saving access paths. The access path (ACCPTH) parameter on the SAVCHGOBJ, SAVLIB, and SAVOBJ commands allows you to save access paths. Normally, only the descriptions of logical les are saved; however, the access paths are saved under the following conditions: v ACCPTH(*YES) is specied. v All physical les under the logical le are being saved and are in the same library. v The logical le is MAINT(*IMMED) or MAINT(*DLY). Note: With the ACCPTH(*YES) parameter the logical le, itself, is not saved. You have to explicitly save the logical le. See the Backup and Recovery book for additional information.

Restoring Access Paths

Access paths can be restored if they were saved and if all the physical les on which they depend are restored at the same time. See the Backup and Recovery book for additional information. Restoring an access path can be faster than rebuilding it. For example, assume a logical le is built over a physical le containing 500,000 records and you have determined (through the Display Object Description [DSPOBJD] command) that the size of the logical le is about 15 megabytes. In this example, assume it would take about 50 minutes to rebuild the access path for the logical le compared to about 1 minute to restore the same access path from a tape. (This assumes that the system can build approximately 10,000 index entries per minute.) After restoring the access path, the le may need to be brought up-to-date by applying the latest journal changes (depending on whether journaling is active). For example, the system can apply approximately 80,000 to 100,000 journal entries per hour, assuming that each of the physical les to which entries are being applied has only one access path built over it. This rate will drop proportionally
Chapter 13. Database Recovery Considerations

217

for each access path of *IMMED maintenance that is present over the physical le. Even with this additional recovery time, you will usually nd it is faster to restore access paths rather than to rebuild them.

Rebuilding Access Paths

Rebuilding a database access path may take as much as one minute for every 10,000 records. Note: This estimate should be used until actual times for your system can be calculated. The following factors affect this time estimate (listed in general order of signicance): v Storage pool size. The size of the storage pool used to rebuild the access path is a very important factor. You can improve the rebuild time by running the job in a larger storage pool. v The system model. The speed of the processing unit is a key factor in the time needed to rebuild an access path. v Key length. A large key length will slow rebuilding the access path because more key information must be constructed and stored in the access path. v Select/omit values. Select/omit processing will slow the rebuilding of an access path because each record must be compared to see if it meets the select/omit values. v Record length. A large record length will slow the rebuilding of an access path because more data is looked at. v Storage device containing the data. The relative speed of the storage device containing the actual data and the device where the access path is stored has an effect on the time needed to rebuild an access path. v The order of the records in the le. The system tries to rebuild an access path so that it can nd information quickly when using that access path. The order of the records in a le has a small affect on how fast the system can build the access path while trying to maintain an efficient access path. v The type of access path. Encoded vector access paths, which you create with the SQL CREATE INDEX statement, rebuild faster because they do not need to scan the underlying le. You use the CHGLF command to allow for an encoded vector access path to be rebuilt directly; to do this, specify *YES on the FRCRBDAP parameter. All of the preceding factors must be considered when estimating the amount of time to rebuild an access path.

| | | | |

Controlling When Access Paths Are Rebuilt

If the system ends abnormally, during the next IPL the system automatically lists those les requiring access path recovery. You can decide whether to rebuild the access path: v During the IPL v After the IPL v When the le is rst used You can also: v Change the scheduling order in which the access paths are rebuilt

218

OS/400 DB2 for AS/400 Database Programming V4R3

v Hold rebuilding of an access path indenitely v Continue the IPL process while access paths with a sequence value that is less than or equal to the *IPL threshold value are rebuilding v Control the rebuilding of access paths after the system has completed the IPL process by using the Edit Rebuild of Access Paths (EDTRBDAP) command The IPL threshold value is used to determine which access paths rebuild during the IPL. All access paths with a sequence value that is less than or equal to the IPL threshold value rebuild during the IPL. Changing the IPL threshold value to 99 means that all access paths with a sequence value of 1 through 99 rebuild during the IPL. Changing the IPL threshold value to 0 means that no access paths rebuild until after the system completes its IPL, except access paths that were being journaled and access paths for system les. The access path recovery value for a le is determined by the value you specied for the RECOVER parameter on the create and change le commands. The default recovery value for *IPL (rebuild during IPL) is 25 and the default value for *AFTIPL (rebuild after IPL) is 75; therefore, RECOVER(*IPL) will show as 25. The initial IPL threshold value is 50; this allows the parameters to affect when the access path is rebuilt. You can override this value on the Edit Rebuild of Access Paths display. If a le is not needed immediately after IPL time, specify that the le can be rebuilt at a later time. This should help reduce the number of les that need to be rebuilt at IPL, allowing the system to complete its IPL much faster. For example, you can specify that all les that must have their access paths rebuilt should rebuild the access paths when the le is rst used. In this case, no access paths are rebuilt at IPL. You can control the order in which the access paths are rebuilt by running only those programs that use the les you want rebuilt rst. This method shortens the IPL time (because there are no access paths to rebuild during the IPL) and could make the rst of several applications available faster. However, the overall time to rebuild all the access paths probably is longer (because there may be other work running when the access paths are being rebuilt, and there may be less main storage available to rebuild the access paths).

Designing Files to Reduce Access Path Rebuilding Time

File design can also help reduce access path recovery time. For example, you might divide a large master le into a history le and a transaction le. The transaction le would be used for adding new data, the history le would be used for inquiry only. On a daily basis, you might merge the transaction data into the history le, then clear the transaction le for the next days data. With this design, the time to rebuild access paths could be shortened. That is, if the system abnormally ended during the day the access path to the smaller transaction le might need to be rebuilt. However, the access path to the large history le, being read-only for most of the day, would rarely be out of synchronization with its data, thereby signicantly reducing the chances that it would have to be rebuilt. Consider the trade-off between using a le design to reduce access path rebuilding time and using system-supplied functions like access path journaling. The le design described above may require a more complex application design. After evaluating your situation, you may decide to use system-supplied functions like access path journaling rather than design more complex applications.

Chapter 13. Database Recovery Considerations

219

Journaling Access Paths

Journaling access paths can signicantly reduce recovery time by reducing the number of access paths that need to be rebuilt after an abnormal system end. Note: Journaling access paths is strongly recommended for AS/400 Version 2 Release 2 and following releases, because access paths may become much larger and may therefore require more time to rebuild. When you journal database les, images of changes to the records in the le are recorded in the journal. These record images are used to recover the le should the system end abnormally. However, after an abnormal end, the system may nd that access paths built over the le are not synchronized with the data in the le. If an access path and its data are not synchronized, the system must rebuild the access path to ensure that the two are synchronized and usable. When access paths are journaled, the system records images of the access path in the journal to provide known synchronization points between the access path and its data. By having that information in the journal, the system can recover both the data les and the access paths, and ensure that the two are synchronized. In such cases, the lengthy time to rebuild the access paths can be avoided. In addition, journaling access paths works with other recovery functions on the system. For example, the system has a number of options to help reduce the time required to recover from the failure and replacement of a disk unit. These options include user auxiliary storage pools and checksum protection. While these options reduce the chances that the entire system must be reloaded because of the disk failure, they do not change the fact that access paths may need to be rebuilt when the system is started following replacement of the failed disk. By using access path journaling and some of the recovery options discussed previously, you can reduce your chances of having to reload the entire system and having to rebuild access paths. Journaling access paths that you know are used in referential integrity relationships helps prevent their constraints from being placed in check pending. See Chapter 16. Referential Integrity for more information on referential integrity. Journaling access paths is easy to start. You can use either the system-managed access-path protection (SMAPP) facility (see System-Managed Access-Path Protection (SMAPP) on page 221) or manage the journaling environment yourself with the Start Journal Access Path (STRJRNAP) command. The STRJRNAP command is used to start journaling the access path for the specied le. You can journal access paths that have a maintenance attribute of immediate (*IMMED) or delayed (*DLY). Once journaling is started, the system continues to protect the access path until the access path is deleted or you run the End Journal Access Path (ENDJRNAP) command for that access path. Before journaling an access path, you must journal the physical les associated with the access path. In addition, you must use the same journal for the access path and its associated physical les. Access path journaling is designed to minimize additional output operations. For example, the system will write the journal data for the changed record and the changed access path in the same output operation. However, you should seriously consider isolating your journal receivers in user auxiliary storage pools when you

220

OS/400 DB2 for AS/400 Database Programming V4R3

start journaling your access paths. Placing journal receivers in their own user auxiliary storage pool provides the best journaling performance, while helping to protect them from a disk failure. See the Backup and Recovery book for more information about journaling access paths.

System-Managed Access-Path Protection (SMAPP)

System-managed access-path protection (SMAPP) provides automatic protection for access paths. Using the SMAPP support, you do not have to use the journaling commands, such as STRJRNAP, to get the benets of access path journaling. SMAPP support recovers access paths after an abnormal system end rather than rebuilding them during IPL. The SMAPP support is turned on with the shipped system and is set to a value of 150 minutes. The system determines which access paths to protect based on target access path recovery times provided by the user or by using a system-provided default time. The target access path recovery times can be specied as a system-wide value or on an ASP basis. Access paths that are being journaled to a user-dened journal are not eligible for SMAPP protection because they are already protected. See the Backup and Recovery book for more information about SMAPP.

Other Methods to Avoid Rebuilding Access Paths

If you do not journal your access paths, or do not take advantage of SMAPP, then you might consider some other system functions that can help you reduce the chances of having to rebuild access paths. The method used by the system to determine if an access path needs to be rebuilt is a le synchronization indicator. Normally the synchronization indicator is on, indicating that the access path and its associated data are synchronized. When a job changes a le that affects an access path, the system turns off the synchronization indicator in the le. If the system ends abnormally, it must rebuild any access path whose le has its synchronization indicator off. To reduce the number of access paths that must be rebuilt, you need a way to periodically synchronize the data with its access path. There are several methods to synchronize a le with its access path: v Full le close. The last full (that is, not shared) system-wide close performed against a le will synchronize the access path and the data. v Force access path. The force-access-path (FRCACCPTH) parameter can be specied on the create or change le commands. v Force write ratio of 2 or greater. The force-write-ratio (FRCRATIO) parameter can be specied on the create, change, or override database le commands. v Force end of data. The les data and its access path can be synchronized by running the force-end-of-data operation in your program. (Some high-level languages do not have a force-end-of-data operation. See your high-level language guide for further details.) Keep in mind that while the data and its access path are synchronized after performing one of the methods mentioned previously, the next change to the data in the le can cause the synchronization indicator to be turned off again. It is also important to note that each of the methods can be costly in terms of performance;
Chapter 13. Database Recovery Considerations

221

therefore, they should be used with caution. Consider journaling access paths, along with saving access paths or using SMAPP, as the primary means of protecting access paths.

Database Recovery after an Abnormal System End

After an abnormal system end, the system proceeds through several automatic recovery steps. This includes such things as: rebuilding the system directory and synchronizing the journal to the les being journaled. The system performs recovery operations during IPL and after IPL.

Database File Recovery during the IPL

During IPL, nothing but the recovery function is active on the system. During IPL, database le recovery consists of the following: v The following functions that were in progress when the system ended are completed: Delete le Remove member Rename member Move object Rename object Change object owner

Change le Change member Grant authority Revoke authority Start journal physical le Start journal access path End journal physical le End journal access path

Change journal Delete journal Recover SQL views Remove physical le constraint v The following functions that were in progress when the system ended are backed out (you must run them again): Create le Add member Create journal Restore journal Add physical le constraint v If the operator is doing the IPL (attended IPL), the Edit Rebuild of Access Paths display appears on the operators display. The display allows the operator to edit the RECOVER option for the les that were in use for which immediate or delayed maintenance was specied. (See Controlling When Access Paths Are Rebuilt on page 218 for information about the IPL threshold value.) If all access paths are valid, or the IPL is unattended, no displays appear.

222

OS/400 DB2 for AS/400 Database Programming V4R3

v Access paths that have immediate or delayed maintenance, and that are specied for recovery during IPL (from the RECOVER option or changed by the Edit Rebuild of Access Paths display) are rebuilt and a message is sent to the history log. Files with journaled access paths that were in use, and system les with access paths that are not valid, are not displayed on the Edit Rebuild of Access Paths display. They are automatically recovered and a message is sent to the history log. v For unattended IPLs, if the system value QDBRCVYWT is 1 (wait), les that were in use that are specied for recovery after IPL are treated as les specied for recovery during IPL. See the Work Management book for more information on the system value QDBRCVYWT. v Verify referential constraints that are in check pending and a message is sent to the history log. v Messages about the following information are sent to the history log: The success or failure of the previously listed items The physical le members that were open when the system ended abnormally and the last active relative record number in each member The physical le members that could not be synchronized with the journal That IPL database recovery has completed

Database File Recovery after the IPL

This recovery step is run after the IPL is complete. Interactive users may be active and batch jobs may be running with this step of database recovery. Recovery after the IPL consists of the following: v The access paths for immediate or delayed maintenance les which specify recovery after IPL, are rebuilt (see Table 12 on page 224). v Messages are sent to the system history log indicating the success or failure of the rebuild operation. v After IPL completion, the Edit Rebuild of Access Paths (EDTRBDAP) command can be used to order the rebuilding of access paths. v After IPL completion, the Edit Check Pending Constraints (EDTCPCST) command displays a list of the physical le constraints in check pending. You can use this command to specify the sequence of the verication of the check pending constraints. Note: If you are not using journaling for a le, records may or may not exist after IPL recovery, as follows: v For added records, if after the IPL recovery the Nth record added exists, then all records added preceding N also exist. v For updated and deleted records, if the update or delete to the Nth record is present after the IPL recovery, there is no guarantee that the records updated or deleted prior to the Nth record are also present in the database. v For REUSEDLT(*YES), records added are treated as updates, and thus, there is no guarantee that records exist after IPL recovery.

Database File Recovery Options Table

The table below summarizes the le recovery options:
Chapter 13. Database Recovery Considerations

223

Table 12. Relationship of Access Path, Maintenance, and Recovery RECOVER Parameter Specied Access Path/ Maintenance Keyed sequence access path/ immediate or delayed maintenance *NO v No database recovery at IPL v File available immediately v Access path rebuilt rst time le opened *AFTIPL v Access path rebuilt after IPL *IPL v Access path rebuilt during IPL

Keyed sequence access path v No database recovery at rebuild maintenance IPL v File available immediately v Access path rebuilt rst time le opened

v Not applicable; no recovery is done for rebuild maintenance

v Not applicable; no recovery is done for rebuild maintenance

Arrival sequence access path

v No database recovery at IPL v File available immediately

v Not applicable; no recovery is done for an arrival sequence access path

v Not applicable; no recovery is done for an arrival sequence access path

Storage Pool Paging Option Effect on Database Recovery

The shared pool paging option controls whether the system dynamically adjusts the paging characteristics of the storage pool for optimum performance. v The system does not dynamically adjust paging characteristics for a paging option of *FIXED. v The system dynamically adjusts paging characteristics for a paging option of *CALC. v You can also control the paging characteristics through an application programming interface. For more information, see Change Pool Tuning Information API(QWCCHGTN) in the System API Reference book. A shared pool paging option other than *FIXED can have an impact on data loss for nonjournaled physical les in a system failure. When you do not journal physical les, data loss from a system failure, where memory is not saved, can increase for *CALC or USRDFN paging options. File changes may be written to auxiliary storage less frequently for these options. There is a risk of data loss for nonjournaled les with the *FIXED option, but the risk can be higher for *CALC or user dened (USRDFN) paging options. For more information on the paging option see the Automatic System Tuning section of the Work Management book

224

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 14. Using Source Files

This chapter describes source les. Source le concepts are discussed, along with why you would use a source le. In addition, this chapter describes how to set up a source le, how to enter data into a source le, and how to use that source le to create another object (for example, a le or program) on the system.

Source File Concepts

A source le is used when a command alone cannot supply sufficient information for creating an object. It contains input (source) data needed to create some types of objects. For example, to create a control language (CL) program, you must use a source le containing source statements, which are in the form of commands. To create a logical le, you must use a source le containing DDS. To create the following objects, source les are required: v High-level language programs v Control language programs v Logical les v Intersystem communications function (ICF) les v Commands v Translate tables To create the following objects, source les can be used, but are not required: v Physical les v Display les v Printer les A source le can be a database le, diskette le, tape le, or inline data le. (An inline data le is included as part of a job.) A source database le is simply another type of database le. You can use a source database le like you would any other database le on the system.

Creating a Source File

To create a source le, you can use the Create Source Physical File (CRTSRCPF), Create Physical File (CRTPF), or Create Logical File (CRTLF) command. Normally, you will use the CRTSRCPF command to create a source le, because many of the parameters default to values that you usually want for a source le. (If you want to use DDS to create a source le, then you would use the CRTPF or CRTLF command.) The CRTSRCPF command creates a physical le, but with attributes appropriate for source physical les. For example, the default record length for a source le is 92 (80 for the source data eld, 6 for the source sequence number eld, and 6 for the source date eld). The following example shows how to create a source le using the CRTSRCPF command and using the command defaults:
Copyright IBM Corp. 1997, 1998

225

CRTSRCPF FILE(QGPL/FRSOURCE) TEXT('Source file')

IBM-Supplied Source Files

For your convenience, the OS/400 program and other licensed programs provide a database source le for each type of source. These source les are:
File Name QBASSRC QCBLSRC QCSRC QCLSRC QCMDSRC QFTNSRC QDDSSRC QFMTSRC QLBLSRC QS36SRC QAPLISRC QPLISRC QREXSRC QRPGSRC QARPGSRC QRPG2SRC QS36SRC QPASSRC QTBLSRC QTXTSRC Library Name QGPL QGPL QGPL QGPL QGPL QGPL QGPL QGPL QGPL #LIBRARY QPLI QGPL QGPL QRPG QRPG38 #RPGLIB #LIBRARY QPAS QGPL QPDA Used to Create BASIC programs System/38 compatible COBOL C programs CL programs Command denition statements FORTRAN programs Files Sort source COBOL/400 programs System/36 compatible COBOL programs PL/I programs PL/I programs Procedures Language 400/REXX programs RPG/400 programs System/38 environment RPG System/36 compatible RPG II System/36 compatible RPG II (after install) Pascal programs Translation tables Text

You can either add your source members to these les or create your own source les. Normally, you will want to create your own source les using the same names as the IBM-supplied les, but in different libraries (IBM-supplied les may get overlaid when a new release of the system is installed). The IBM-supplied source les are created with the le names used for the corresponding create command (for example, the CRTCLPGM command uses the QCLSRC le name as the default). Additionally, the IBM-supplied programmer menu uses the same default names. If you create your own source les, do not place them in the same library as the IBM-supplied source les. (If you use the same le names as the IBM-supplied names, you should ensure that the library containing your source les precedes the library containing the IBM-supplied source les in the library list.)

Source File Attributes

Source les usually have the following attributes: v A record length of 92 characters (this includes a 6-byte sequence number, a 6-byte date, and 80 bytes of source).

226

OS/400 DB2 for AS/400 Database Programming V4R3

v Keys (sequence numbers) that are unique even though the access path does not specify unique keys. You are not required to specify a key for a source le. Default source les are created without keys (arrival sequence access path). A source le created with an arrival sequence access path requires less storage space and reduces save/restore time in comparison to a source le for which a keyed sequence access path is specied. v More than one member. v Member names that are the same as the names of the objects that are created using them. v The same record format for all records. v Relatively few records in each member compared to most data les. Some restrictions are: v The source sequence number must be used as a key, if a key is specied. v The key, if one is specied, must be in ascending sequence. v The access path cannot specify unique keys. v The ALTSEQ keyword is not allowed in DDS for source les. v The rst eld must be a 6-digit sequence number eld containing zoned decimal data and two decimal digits. v The second eld must be a 6-digit date eld containing zoned decimal data and zero decimal digits. v All elds following the second eld must be zoned decimal or character.

Creating Source Files without DDS

When you create a source physical le without using DDS, but by specifying the record length (RCDLEN parameter), the source created contains three elds: SRCSEQ, SRCDAT, and SRCDTA. (The record length must include 12 characters for sequence number and date-of-last-change elds so that the length of the data portion of the record equals the record length minus 12.) The data portion of the record can be dened to contain more than one eld (each of which must be character or zoned decimal). If you want to dene the data portion of the record as containing more than one eld, you must dene the elds using DDS. A record format consisting of the following three elds is automatically used for a source physical le created using the Create Source Physical File (CRTSRCPF) command:
Field 1 2 3 Name SRCSEQ SRCDAT SRCDTA Data Type and Length Description Zoned decimal, 6 digits, 2 Sequence number for decimal positions record Zoned decimal, 6 digits, Date of last update of no decimal positions record Character, any length Data portion of the record (text)

Note: For all IBM-supplied database source les, the length of the data portion is 80 bytes. For IBM-supplied device source les, the length of the data portion is the maximum record length for the associated device.

Chapter 14. Using Source Files

227

Creating Source Files with DDS

If you want to create a source le for which you need to dene the record format, use the Create Physical File (CRTPF) or Create Logical File (CRTLF) command. If you create a source logical le, the logical le member should only refer to one physical le member to avoid duplicate keys.

Working with Source Files

The following section describes how to enter and maintain data in your source les.

Using the Source Entry Utility (SEU)

You can use the Source Entry Utility (SEU), to enter and change source in a source le. If you use SEU to enter source in a database le, SEU adds the sequence number and date elds to each source record. If you use SEU to update a source le, you can add records between existing records. For example, if you add a record between records 0003.00 and 0004.00, the sequence number of the added record could be 0003.01. SEU will automatically arrange the newly added statements in this way. When records are rst placed in a source le, the date eld is all zoned decimal zeros (unless DDS is used with the DFT keyword specied). If you use SEU, the date eld changes in a record when you change the record.

Using Device Source Files

Tape and diskette unit les can be created as source les. When device les are used as source les, the record length must include the sequence number and date elds. Any maximum record length restrictions must consider these additional 12 characters. For example, the maximum record length for a tape record is 32 766. If data is to be processed as source input, the actual tape data record has a maximum length of 32 754 (which is 32 766 minus 12). If you open source device les for input, the system adds the sequence number and date elds, but there are zeros in the date elds. If you open a device le for output and the le is dened as a source le, the system deletes the sequence number and date before writing the data to the device.

Copying Source File Data

The Copy Source File (CPYSRCF) and Copy File (CPYF) commands can be used to write data to and from source le members. When you are copying from a database source le to another database source le that has an insert trigger associated with it, the trigger program is called for each record copied.

228

OS/400 DB2 for AS/400 Database Programming V4R3

Using the Copy Source File (CPYSRCF) Command for Copying to and from Source Files
The CPYSRCF command is designed to operate with database source les. Although it is similar in function to the Copy File (CPYF) command, the CPYSRCF command provides defaults that are normally used when copying a source le. For example, it has a default that assumes the TOMBR parameter is the same as the FROMMBR parameter and that any TOMBR records will always be replaced. The CPYSRCF command also supports a unique printing format when TOFILE(*PRINT) is specied. Therefore, when you are copying database source les, you will probably want to use the CPYSRCF command. The CPYSRCF command automatically converts the data from the from-le CCSID to the to-le CCSID.

Using the Copy File (CPYF) Command for Copying to and from Files
The CPYF command provides additional functions over the CPYSRCF command such as: v Copying from database source les to device les v Copying from device les to database source les v Copying between database les that are not source les and source database les v Printing a source member in hexadecimal format v Copying source with selection values

Source Sequence Numbers Used in Copies

When you copy to a database source le, you can use the SRCOPT parameter to update sequence numbers and initialize dates to zeros. By default, the system assigns a sequence number of 1.00 to the rst record and increases the sequence numbers by 1.00 for the remaining records. You can use the SRCSEQ parameter to set a fractional increased value and to specify the sequence number at which the renumbering is to start. For example, if you specify in the SRCSEQ parameter that the increased value is .10 and is to start at sequence number 100.00, the copied records have the sequence numbers 100.00, 100.10, 100.20, and so on. If a starting value of .01 and an increased value of .01 are specied, the maximum number of records that can have unique sequence numbers is 999,999. When the maximum sequence number (9999.99) is reached, any remaining records will have a sequence number of 9999.99. The following is an example of copying source from one member to another in the same le. If MBRB does not exist, it is added; if it does exist, all records are replaced.
CPYSRCF FROMFILE(QCLSRC) TOFILE(QCLSRC) FROMMBR(MBRA) + TOMBR(MBRB)

The following is an example of copying a generic member name from one le to another. All members starting with PAY are copied. If the corresponding members do not exist, they are added; if they do exist, all records are replaced.
CPYSRCF FROMFILE(LIB1/QCLSRC) TOFILE(LIB2/QCLSRC) + FROMMBR(PAY*)

Chapter 14. Using Source Files

229

The following is an example of copying the member PAY1 to the printer le QSYSPRT (the default for *PRINT). A format similar to the one used by SEU is used to print the source statements.
CPYSRCF FROMFILE(QCLSRC) TOFILE(*PRINT) FROMMBR(PAY1)

When you copy from a device source le to a database source le, sequence numbers are added and dates are initialized to zeros. Sequence numbers start at 1.00 and are increased by 1.00. If the le being copied has more than 9999 records, then the sequence number is wrapped back to 1.00 and continues to be increased unless the SRCOPT and SRCSEQ parameters are specied. When you are copying from a database source le to a device source le, the date and sequence number elds are removed.

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

Loading and Unloading Data from Non-AS/400 Systems

You can use the Copy From Import File (CPYFRMIMPF) and Copy To Import File (CPYTOIMPF) commands to import (load) or export (unload) data from and to the AS/400. To import data from a non-AS/400 database into an externally-described DB2 for AS/400 database le, perform the following steps: 1. Create an import le for the data that you want to copy. The import le can be a database source le or an externally-described database le that has 1 eld. The eld must have a data type of CHARACTER, IGC OPEN, IGC EITHER, IGC ONLY, or UCS-2. 2. Send the data to the import le (or, the from le). The system performs any required ASCII to EBCDIC conversion during this process. You can send the data in several ways: v TCP/IP le transfer (le transfer) v Client Access support (le transfer, ODBC) v Copy From Tape File (CPYFRMTAP) command 3. Create an externally-described DB2 for AS/400 database le, or a DDM le, into which you want to copy the data. 4. Use the Copy From Import File (CPYFRMIMPF) command to copy the data from the import le to your AS/400 database le. If you have the DB2 Symmetric Multiprocessing product installed on your system, the system will copy the le in parallel. To export AS/400 database data to another system, use the Copy To Import File (CPYTOIMPF) command to copy the data from your database le to the import le. Then send the data to the system to which you are exporting the data. For more information about importing and exporting database les, see the DB2 information in the AS/400 Information Center.

Using Source Files in a Program

You can process a source le in your program. You can use the external denition of the source le and do any input/output operations for that le, just as you would for any other database le.

230

OS/400 DB2 for AS/400 Database Programming V4R3

Source les are externally described database les. As such, when you name a source le in your program and compile it, the source le description is automatically included in your program printout. For example, assume you wanted to read and update records for a member called FILEA in the source le QDDSSRC. When you write the program to process this le, the system will include the SRCSEQ, SRCDAT, and SRCDTA elds from the source le. Note: You can display the elds dened in a le by using the Display File Field Description command (DSPFFD). For more information about this command, see Displaying the Descriptions of the Fields in a File on page 206 . The program processing the FILEA member of the QDDSSRC le could: v Open the le member (just like any other database le member). v Read and update records from the source le (probably changing the SRCDTA eld where the actual source data is stored). v Close the source le member (just like any other database le member).

Creating an Object Using a Source File

You can use a create command to create an object using a source le. If you create an object using a source le, you can specify the name of the source le on the create command. For example, to create a CL program, you use the Create Control Language Program (CRTCLPGM) command. A create command species through a SRCFILE parameter where the source is stored. The create commands are designed so that you do not have to specify source le name and member name if you do the following: 1. Use the default source le name for the type of object you are creating. (To nd the default source le name for the command you are using, see IBM-Supplied Source Files on page 226.) 2. Give the source member the same name as the object to be created. For example, to create the CL program PGMA using the command defaults, you would simply type:
CRTCLPGM PGM(PGMA)

The system would expect the source for PGMA to be in the PGMA member in the QCLSRC source le. The library containing the QCLSRC le would be determined by the library list. As another example, the following Create Physical File (CRTPF) command creates the le DSTREF using the database source le FRSOURCE. The source member is named DSTREF. Because the SRCMBR parameter is not specied, the system assumes that the member name, DSTREF, is the same as the name of the object being created.
CRTPF FILE (QGPL/DSTREF) SRCFILE(QGPL/FRSOURCE)

Chapter 14. Using Source Files

231

Creating an Object from Source Statements in a Batch Job

If your create command is contained in a batch job, you can use an inline data le as the source le for the command. However, inline data les used as a source le should not exceed 10,000 records. The inline data le can be either named or unnamed. Named inline data les have a unique le name that is specied on the //DATA command. For more information about inline data les, see the Data Management book. Unnamed inline data les are les without unique le names; they are all named QINLINE. The following is an example of an inline data le used as a source le:
//BCHJOB CRTPF FILE(DSTPRODLB/ORD199) SRCFILE(QINLINE) //DATA FILETYPE(*SRC) . . (source statements) . // //ENDBCHJOB

In this example, no le name was specied on the //DATA command. An unnamed spooled le was created when the job was processed by the spooling reader. The CRTPF command must specify QINLINE as the source le name to access the unnamed le. The //DATA command also species that the inline le is a source le (*SRC specied for the FILETYPE parameter). If you specify a le name on the //DATA command, you must specify the same name on the SRCFILE parameter on the CRTPF command. For example:
//BCHJOB CRTPF FILE(DSTPRODLB/ORD199) SRCFILE(ORD199) //DATA FILE(ORD199) FILETYPE(*SRC) . . (source statements) . // //ENDBCHJOB

If a program uses an inline le, the system searches for the rst inline le of the specied name. If that le cannot be found, the program uses the rst le that is unnamed (QINLINE). If you do not specify a source le name on a create command, an IBM-supplied source le is assumed to contain the needed source data. For example, if you are creating a CL program but you did not specify a source le name, the IBM-supplied source le QCLSRC is used. You must have placed the source data in QCLSRC. If a source le is a database le, you can specify a source member that contains the needed source data. If you do not specify a source member, the source data must be in a member that has the same name as the object being created.

Determining Which Source File Member Was Used to Create an Object

When an object is created from source, the information about the source le, library, and member is held in the object. The date/time that the source member was last changed before object creation is also saved in the object.

232

OS/400 DB2 for AS/400 Database Programming V4R3

The information in the object can be displayed with the Display Object Description (DSPOBJD) command and specifying DETAIL(*SERVICE). This information can help you in determining which source member was used and if the existing source member was changed since the object was created. You can also ensure that the source used to create an object is the same as the source that is currently in the source member using the following commands: v The Display File Description (DSPFD) command using TYPE(*MBR). This display shows both date/times for the source member. The Last source update date/time value should be used to compare to the Source file date/time value displayed from the DSPOBJD command. v The Display Object Description (DSPOBJD) command using DETAIL(*SERVICE). This display shows the date/time of the source member used to create the object. Note: If you are using the data written to output les to determine if the source and object dates are the same, then you can compare the ODSRCD (source date) and ODSRCT (source time) elds from the output le of the DSPOBJD DETAIL(*SERVICE) command to the MBUPDD (member update date) and MBUPDT (member update time) elds from the output le of the DSPFD TYPE(*MBR) command.

Managing a Source File

This section describes several considerations for managing source les.

Changing Source File Attributes

If you are using SEU to maintain database source les, see the ADTS for AS/400: Source Entry Utility book for information on how to change database source les. If you are not using SEU to maintain database source les, you must totally replace the existing member. If your source le is on a diskette, you can copy it to a database le, change it using SEU, and copy it back to a diskette. If you do not use SEU, you have to delete the old source le and create a new source le. If you change a source le, the object previously created from the source le does not match the current source. The old object must be deleted and then created again using the changed source le. For example, if you change the source le FRSOURCE created in Creating an Object Using a Source File on page 231, you have to delete the le DSTREF that was created from the original source le, and create it again using the new source le so that DSTREF matches the changed FRSOURCE source le.

Reorganizing Source File Member Data

You usually do not need to reorganize a source le member if you use arrival sequence source les. To assign unique sequence numbers to all the records, specify the following parameters on the Reorganize Physical File Member (RGZPFM) command: v KEYFILE(*NONE), so that the records are not reorganized
Chapter 14. Using Source Files

233

v SRCOPT(*SEQNBR), so that the sequence numbers are changed v SRCSEQ with a fractional value such as .10 or .01, so that all the sequence numbers are unique Note: Deleted records, if they exist, will be compressed out. A source le with an arrival sequence access path can be reorganized by sequence number if a logical le for which a keyed sequence access path is specied is created over the physical le.

Determining When a Source Statement Was Changed

Each source record contains a date eld which is automatically updated by SEU if a change occurs to the statement. This can be used to determine when a statement was last changed. Most high-level language compilers print these dates on the compiler lists. The Copy File (CPYF) and Copy Source File (CPYSRCF) commands also print these dates. Each source member description contains two date and time elds. The rst date/time eld reects changes to the member any time it is closed after being updated. The second date/time eld reects any changes to the member. This includes all changes caused by SEU, commands (such as CRYF and CPYSRCF), authorization changes, and changes to the le status. For example, the FRCRATIO parameter on the Change Physical File (CHGPF) command changes the member status. This date/time eld is used by the Save Changed Objects (SAVCHGOBJ) command to determine if the member should be saved. Both date/time elds can be displayed with the Display File Description (DSPFD) command specifying TYPE(*MBR). There are two changed date/times shown with source members: v Last source update date/time. This value reects any change to the source data records in the member. When a source update occurs, the Last change date/time value is also updated, although there may be a 1- or 2-second difference in that date/time value. v Last change date/time. This value reects any changes to the member. This includes all changes caused by SEU, commands (such as CPYF and CPYSRCF), authorization changes, or changes to le status. For example, the FRCRATIO parameter on the CHGPF command changes the member status, and therefore, is reected in the Last change date/time value.

Using Source Files for Documentation

You can use the IBM-supplied source le QTXTSRC to help you create and update online documentation. You can create and update QTXTSRC members just like any other application (such as QRPGSRC or QCLSRC) available with SEU. The QTXTSRC le is most useful for narrative documentation, which can be retrieved online or printed. The text that you put in a source member is easy to update by using the SEU add, change, move, copy, and include operations. The entire member can be printed by specifying Yes for the print current source le option on the exit prompt. You can also write a program to print all or part of a source member.

234

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 15. Physical File Constraints

The DB2 for AS/400 database supports the following physical le constraints: v Referential constraints v Primary key constraints v Unique constraints v Check constraints Referential constraint specics are described in Chapter 16. Referential Integrity. Aspects of physical le constraints in general are described in this chapter. Primary key and unique constraints are useful alone and are often necessary when using referential constraints. Unique constraints let you create additional, enforced unique keys for a le beyond the le access path. Unique and primary key constraints are enforced during le insertions, updates, and deletions. Primary key and unique constraints are similar to logical les in that they provide a keyed access path. Check constraints provide another check for the validity of data being added into your database by testing the data in an expression. You can also add and remove constraints with the SQL CREATE TABLE and ALTER TABLE statements. This chapter references the native operating system means of working with physical le constraints, that is, CL commands. For detailed information on DB2 for AS/400 SQL means of working with constraints, see the DB2 for AS/400 SQL Programming and DB2 for AS/400 SQL Reference books.

Unique Constraint
A unique constraint identies a eld or set of elds in a database le that meets all the following: v is unique within the le v is in ascending order v can be null capable A le can have multiple unique constraints, but there cannot be duplicate unique constraints. The same key elds, regardless of order, constitute a duplicate constraint.

Primary Key Constraint

A primary key constraint identies a eld or set of elds in a database le that meets all the following: v is unique within the le v is in ascending order If one or more elds of the primary key are null-capable, a check constraint is implicitly added so that null values cannot be entered into the elds.

Copyright IBM Corp. 1997, 1998

235

Only one primary key constraint can be dened for a le. A primary key constraint is a unique key constraint with special attributes.

Check Constraint
A check constraint assures the validity of data during inserts and updates by checking the data against a search expression that you dene. For example, you can add a check constraint on a eld such that values inserted into that eld must be between 1 and 100. If a value does not fall within that range, the insert or update operation against your database is not processed. Check constraints are much like referential constraints in terms of their states: v Dened and enabled the constraint denition has been added to the le, and the constraint will be enforced when the constraint is established. v Dened and disabled the constraint denition has been added to the le, but the constraint will not be enforced. v Established and enabled the constraint has been added to the le and all of the pieces of the le are there for enforcement. v Established and disabled the constraint has been added to the le and all of the pieces of the le are there for enforcement, but the constraint will not be enforced. A check constraint will be in check pending if the data in any record causes the check constraint expression to be not valid.

Adding Unique, Primary Key, and Check Constraints

To add a physical le constraint, use the Add Physical File Constraint (ADDPFCST) command. v To add a unique constraint, specify a value of *UNQCST on the Type parameter. You must also specify a eld name for the Key parameter. v To add a primary key constraint, specify a value of *PRIKEY on the Type parameter. The key that you specify on the command becomes the les primary access path. If the le does not have a keyed access path that can be shared, the system creates one. You must also specify a eld name for the Key parameter. v To add a check constraint, specify a value of *CHKCST on the Type parameter. You must also specify an expression on the CHKCST parameter. The check constraint expression has the same syntax as the SQL checkcondition. The KEY parameter is required when adding unique and primary key constraints. For information on adding referential constraints, see Chapter 16. Referential Integrity.

Removing Constraints
The Remove Physical File Constraint (RMVPFCST) command removes a constraint.

236

OS/400 DB2 for AS/400 Database Programming V4R3

The full impact of the RMVPFCST command depends on what constraint you request be removed and certain conditions surrounding the constraint. The TYPE parameter species the type of constraint to remove: v Unique constraints: TYPE(*UNQCST) All unique constraints except the primary key constraint are removed when CST(*ALL) is specied The named unique constraint for CST(constraint-name) v Primary key constraints: TYPE(*PRIKEY) The primary constraint is removed when CST(*ALL) is specied The named primary constraint for CST(constraint-name) v Check constraints: TYPE(*CHKCST) All check constraints are removed when CST(*ALL) is specied The named check constraint for CST(constraint-name) All check constraints in check pending are removed for CST(*CHKPND) If you remove a primary key constraint or unique constraint and the associated access path is shared by a logical le, the ownership of the shared path is transferred to the logical le. If the access path is not shared, it is removed. When you remove a primary key constraint with the RMVPFCST command, the system sends an inquiry message asking if the key specications should be removed from the le. A reply of K indicates keep the key specications in the le. The le remains keyed. A reply of G indicates the le will have an arrival sequence access path when the command completes. When you remove a primary key constraint with the SQL ALTER TABLE, the inquiry message is not sent. The key specications are always removed and the le will have an arrival sequence access path when the ALTER TABLE completes. For information on removing referential constraints, see Chapter 16. Referential Integrity.

Working With Physical File Constraints

The Work with Physical File Constraints (WRKPFCST) command displays a list of constraints that includes the constraint name, le and library name, type, state, and whether it is in check pending. From this display you can change or remove a constraint. You can also display a list of the records that have caused a le to be put into check pending.

Chapter 15. Physical File Constraints

237

Work with Physical File Constraints Type options, press Enter. 2=Change 4=Remove 6=Display records in check pending Opt _ _ _ _ _ _ _ _ _ Constraint File Library DEPTCST EMPDIV7 EPPROD ACCTCST EMPDIV7 EPPROD STAT84 EMPDIV7 EPPROD FENSTER REVSCHED EPPROD IRSSTAT3 REVSCHED EPPROD IFRNUMBERO > REVSCHED EPPROD EVALDATE QUOTOSCHEM EPPROD STKOPT CANSCRONN9 EPPROD CHKDEPT EMPDIV2 EPPROD Type *REFCST *REFCST *REFCST *REFCST *UNQCST *UNQCST *REFCST *PRIKEY *CHKCST State EST/ENB EST/ENB DEF/ENB EST/DSB EST/ENB EST/ENB Check Pending No Yes No Yes No No

Parameters for options 2, 4, 6 or command ===>________________________________________________________ F3=Exit F4=Prompt F5=Refresh F12=Cancel F15=Sort by F16=Repeat position to F17=Position to F22=Display constraint name

Figure 16. Work with Physical File Constraints Display

The display shows all the constraints dened for le specied in the WRKPFCST command. The display lists the constraint names, the le name, and the library name. The Type column identies the constraint as referential, unique, primary key, or check. The State column indicates whether the constraint is dened or established and whether it is enabled or disabled. The nal column contains the check pending status of the constraint. Unique and primary key constraints do not have a state because they are always established and enabled. With this display, you have the following options: v Change (option 2) to any permissible state. For example, you can enable a constraint that is currently disabled. This option performs the same functions as the CHGPFCST command. v Remove (option 4) a constraint. This option performs the same functions as the RMVPFCST command. v Display (option 6) the records that are in check pending. This option performs the same functions as DSPCPCST command. See Check Pending on page 248 for a discussion of check pending and referential constraints.

Displaying Check Pending Constraints

The Display Check Pending Constraints (DSPCPCST) command displays or prints the records that caused the constraint to be marked as check pending. Before using this command, use the Change Physical File Constraint (CHGPFCST) command to disable the constraint. This command may take a long time when the associated les have a large number of records. Figure 17 on page 239 shows how the DSPCPCST command displays the records in check pending. You can use the DSPCPCST command for referential constraints and check constraints.

238

OS/400 DB2 for AS/400 Database Programming V4R3

Display Report Width . . .: 71 Column . .: 1 Control . . . . _________ Line ....+....1....+....2....+....3....+....4....+....5....+.... PARTNUM PARTID QUANTITY -------------------00001 25RFA1 WIDGET 3000 00002 32XGW3 GIZMO 32 ***** * * * * * E N D O F D A T A * * * * *

F3=Exit

F12=Cancel

F19=Left

F20=Right

F21=Split

Bottom

Figure 17. DSPCPCST Display

Processing Check Pending Constraints

The Edit Check Pending Constraints (EDTCPCST) command presents the Editing Check Pending Constraints display shown in Figure 18. This display can help you manage and schedule the verication of physical le constraints placed in check pending. When verifying a physical le constraint, the database must ensure that every record in the le meets the constraint denition. For instance, verication of a referential constraint causes the database to check that every foreign key value has a matching parent key value. See Chapter 16. Referential Integrity for more information on referential constraints.
Edit Check Pending Constraints Type sequence, press Enter. Sequence: 1-99, *HLD Seq 1 1 *HLD *HLD *HLD *HLD Status RUN READY CHKPND CHKPND CHKPND CHKPND ------------Constraints----------Cst File Library EMP1 DEP EPPROD CONST > DEP EPPROD FORTH > STYBAK EPPROD CST88 STYBAK EPPROD CS317 STYBAK EPPROD KSTAN STYBAK EPPROD Verify Time 00:01:00 00:02:00 00:03:00 00:10:00 00:20:00 02:30:00 Elapsed Time 00:00:50 00:00:00 00:00:00 00:00:00 00:00:00 00:00:00

Bottom F3=Exit F5=Refresh F12=Cancel F13=Repeat all F15=Sort by F16=Repeat position to F17=Position to F22=Display constraint name

Figure 18. Edit Check Pending Constraints Display

Chapter 15. Physical File Constraints

239

The status eld of the Edit Check Pending Constraints display has one of the following values: v RUN indicates the constraint is being veried. v READY indicates the constraint is ready to be veried. v NOTVLD indicates the access path associated with the constraint is not valid. Once the access path has been rebuilt, the constraint will be automatically veried by the system. This value applies to referential constraints only. v HELD indicates the constraint is not be veried. You must change the sequence to a value from 1 to 99 to change this state. v CHKPND indicates there has been a attempt to verify the constraint, but the constraint is still in check pending. You must change the sequence to a value from 1 to 99 to change this state. The Constraint column contains the rst ve characters of the constraint name. If the name is followed by a > if it exceeds ve characters. You can display the whole long name by putting the cursor on that line and press the F22 key. The verify time column shows the time it would take to verify the constraint if there were no other jobs on the system. The elapsed time column indicates the time already spent on verifying the constraint. See Check Pending on page 248 for a discussion of check pending and referential constraints.

Physical File Constraint Considerations and Limitations

v A le must be a physical le. v A le can have a maximum of one member, MAXMBR(1). v A constraint can be dened when the le has zero members. A constraint cannot be established until the le has one, and only one, member. v A le can have a maximum of one primary key but may have many parent keys. v There is maximum of 300 constraint relations per le. This maximum value is the sum of: The unique constraints. The primary key constraints. The check constraints. The referential constraints whether participating as a parent or a dependent, and whether the constraints are dened or established. v Constraint names must be unique in a library. v Constraints cannot be added to les in the QTEMP library.

240

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 16. Referential Integrity

This chapter describes the implementation of referential integrity in the DB2/400 database.

Introducing Referential Integrity and Referential Constraints

Referential integrity is a broad term encompassing all the mechanisms and techniques that ensure the validity of referenced data in a relational database. Referential constraints are a mechanism to enforce a level of validity desired in your database. Beginning with Version 3 Release 1 this capability became part of the OS/400 Operating System. Database users want referential integrity implemented in their database management system for several reasons: v To ensure data values between les are kept in a state that meets the rules of their business. For example, if a business has a list of customers in one le and a list of their accounts in another le, it does not make sense to allow the addition of an account if an associated customer does not exist. Likewise, it is not reasonable to delete a customer until all their accounts are deleted. v To be able to dene the relationships between data values. v To have the system enforce the data relationships no matter what application makes changes. v To improve the performance of integrity checks done in a HLL or SQL level by moving the checking into the database.

Referential Integrity Terminology

A discussion of referential integrity requires an understanding of several terms. These terms are in an order that may help you understand their relationship to each other.
Primary Key. A eld or set of elds in a database le that must be unique, ascending, and cannot contain null values. The primary key is the primary le access path. The primary key can become the parent key in the parent le. Unique Key. A eld or set of elds in a database le that must be unique, ascending, and can contain null values. Parent Key. A eld or set of elds in a database le that must be unique, ascending, and may or may not contain null values. The parent key can be the same as the primary key or unique key. It can also be a superset of the primary key. Foreign Key. A eld or set of elds in which each non-null value must match a key value of the related parent le. However, the attributes (data type, length, and so forth) must be the same as the primary or parent key. Referential integrity. The state of a database in which the values of the foreign keys are valid. The enforcement of referential integrity prevents the violation of the non-null foreign key must have a matching parent key rule. Referential constraint. The constraint denes a relationship between the records identied by parent keys and the records identied by foreign keys. Because a dependent le is always dependent upon the parent le, the referential constraint is dened from the dependent les perspective. The constraint cannot be dened from the parent les perspective. Parent le. The le in a relationship containing the parent key or primary key.
Copyright IBM Corp. 1997, 1998

241

Dependent le. The le in a relationship containing the foreign key. Check pending. The state that occurs when the database does not know with certainty that a particular dependent le contains only valid data relative to its associated parent key. Delete rule. A denition of what action the database should take when there is an attempt to delete a parent record. Update rule. A denition of what action the database should take when there is an attempt to update a parent record.

A Simple Referential Integrity Example

A database contains an employee le and a department le. Both les have a department number eld named DEPTNO. The related records of these database les are those for which employee.DEPTNO equals department.DEPTNO.

Employee File NAME DEPTNO SALARY ... Jones 162 36000 ... Harvel-Smith 394 24000 ... Mendes 162 38500 ... Gott 071 47000 ... Biset 071 41300 ...

Constraint Foreign Key Identifies Files Identifies Keys States Rules Parent Key DEPTNO MANAGER AREA 071 Stephens Marketing 162 Abdul Administration 394 Levine Development Department File

Figure 19. Employee and Department Files

The department le is the parent and department.DEPTNO is the parent key. It is also the primary key for the le. The employee le is the dependent le and employee.DEPTNO is the foreign key. Each record in the employee le that has a non-null value for DEPTNO is related to one and only one record in the department le. The constraint on the values of DEPTNO in the employee le is the referential constraint. The constraint identies the les, the keys, and species the rules that must be followed when a user or application makes changes (deletes or updates) to the parent le.

242

OS/400 DB2 for AS/400 Database Programming V4R3

Creating a Referential Constraint

The les involved in a referential constraint relationship must be physical les with a maximum of one member. A referential constraint is a le-level attribute. You can create a constraint denition for a le before the member exists. You can create the member for each le later. Certain conditions must be met before you can create a referential constraint: v There must be a parent le with a key capable of being a parent key. If the parent le has no primary key or unique constraint, the systems tries to add a primary key constraint to the le. v There must be a dependent le with certain attributes that match those of the parent le: Sort sequence (SRTSEQ) must match for data types CHAR, OPEN, EITHER, and HEX. CCSID must match for each SRTSEQ table unless one or both CCSIDs is 65535. Each sort sequence table must match exactly. v The dependent le must contain a foreign key that matches the following attributes of the parent key: Data type Length Precision (if packed, zoned, or binary) CCSID (unless either is 65535) REFSHIFT (if data type is OPEN, EITHER, or ONLY)

Constraint Rules
Referential constraints allows you to specify certain rules for the system to enforce. Referential constraint rules apply to parent key deletes and updates. Constraint rules are set with the Add Physical File Constraint (ADDPFCST) command. Specify the delete rule with the DLTRULE parameter and the update rule with the UPDRULE parameter.

Delete Rules
There are ve possible values for the DLTRULE parameter. The delete rule species the action to be taken when a parent key value is deleted. Null parent key values are not affected by the delete rule. v *NOACTION (This is the default value.) Record deletion in a parent le will not occur if the parent key value has a matching foreign key value. v *CASCADE Record deletion in a parent le causes records with matching foreign key values in the dependent le to be deleted when the parent key value matches the foreign key value. v *SETNULL Record deletion in a parent le updates those records in the dependent le where the parent non-null key value matches the foreign key value. For those

Chapter 16. Referential Integrity

243

dependent records that meet the preceding criteria, all null capable elds in the foreign key are set to null. Foreign key elds with the non-null attribute are not updated. v *SETDFT Record deletion in a parent le updates those records in the dependent le where the parent non-null key value matches the foreign key value. For those dependent records that meet the preceding criteria, the foreign key eld or elds are set to their corresponding default values. v *RESTRICT Record deletion in a parent le will not occur if the parent key value has a matching foreign key value. Note: The system enforces a delete *RESTRICT rule immediately when the deletion is attempted. The system enforces other constraints at the logical end of the operation. The operation, in the case of other constraints, includes an trigger programs that are run before or after the delete. It is possible for a trigger program to correct a potential referential integrity violation. For example, a trigger program could add a parent record if one does not exist. (See Chapter 17. Triggers for information on triggers.) The violation cannot be prevented with the *RESTRICT rule.

Update Rules
There are two possible values for the UPDRULE parameter. The UPDRULE parameter identies the update rule for the constraint relationship between the parent and dependent les. The update rule species the action taken when parent le updating is attempted. v *NOACTION (This is the default value.) Record update in a parent le does not occur if there is a matching foreign key value in the dependent le. v *RESTRICT Record update in a parent le does not occur if there is a non-null parent key value matching a foreign key value. Note: The system enforces an update *RESTRICT rule immediately when the update is attempted. The system enforces other constraints at the logical end of the operation. For example, a trigger program could add a parent record if one does not exist. (See Chapter 17. Triggers for information on triggers.) The violation cannot be prevented with the *RESTRICT rule. If you are performing inserts, updates, or deletes on a le that is associated with a referential constraint and the delete rule, update rule, or both is other than RESTRICT, you must use journaling. Both the parent and dependent les must be journaled to the same journal. In addition, you are responsible for starting the journaling for the parent and dependent les with the Start Journal Physical File (STRJRNPF) command. If you are inserting, updating, or deleting records to a le that is associated with a referential constraint that has a delete rule, update rule, or both rules, other than *RESTRICT, commitment control is required. If you have not started commitment control, it will automatically be started and ended for you.

244

OS/400 DB2 for AS/400 Database Programming V4R3

Dening the Parent File

A parent le must be a physical le with a maximum of one member. You can create the parent le in a constraint with the Create Physical File (CRTPF) command specifying a unique, ascending, and non-null keythe primary key. You can also use an existing le as a parent le. The primary access path to such a le is potentially a parent key. Potentially means the user must explicitly change the access path into a parent key through SQL or the Add Physical File Constraint (ADDPFCST) command. Alternately, a unique key access path can be used as the parent key. A primary key is a unique key with special attributes. If, after the le is created, neither the primary nor unique key will suffice as the parent key, you have the following options: v Delete the le and recreate it with the appropriate keys. v Add a unique or primary key constraint to the created le. There are several ways to use an existing le as a parent le. This usage depends on the circumstances of the existing le and the constraint that is to be associated with the le. v You can add a primary key to a le with the Add Physical File Constraint (ADDPFCST) command specifying *PRIKEY for the TYPE parameter. You must also specify the key eld or elds with the KEY parameter. If a primary key already exists for the le, the ADDPFCST command with TYPE(*PRIKEY) will fail because a le can have only one primary key. You must rst remove the existing primary key with the Remove Physical File Constraint (RMVPFCST) command, then you can add a new primary key. v You can add a unique constraint to a le with the Add Physical File Constraint (ADDPFCST) command specifying *UNQCST for the TYPE parameter. You must also specify the key eld or elds with the KEY parameter. You can also add a unique constraint with SQL ALTER TABLE. If the parent le does not have an existing keyed access path that can be shared for the primary key or unique constraint, the system creates one.

Dening the Dependent File

A dependent le must be a physical le with a maximum of one member. You can create the le as you would any physical le or use an existing le. It is not necessary that the dependent le have a keyed access path when you create the actual constraint. If no existing access paths meet the foreign key criteria, an access path is added to the le by the system. As listed on page 243, the attributes of foreign key eld or elds must match those of the parent key in the parent le.

Verifying Referential Constraints

During the creation of a constraint with the ADDPFCST command, the system veries that every non-null foreign key value has a matching parent key value. It is not uncommon to add a referential constraint to existing les that contain large amounts of data. ADDPFCST can take several hours to complete when a very large
Chapter 16. Referential Integrity

245

number of records are involved. The les are locked exclusively during the add process. You should take the time factor and le availability into account before creating a referential constraint. If the verication is successful, the constraint rules are enforced on subsequent accesses by a user or application program. An unsuccessful verication causes the constraint to be marked as check pending, see Check Pending and the ADDPFCST Command on page 249.

Referential Integrity Enforcement

The I/O access for les associated with established and enabled constraints varies depending on whether the le contains the parent key or foreign key in the constraint relationship. Referential integrity enforcement is performed system-wide on all parent and dependent le I/O requests. The database enforces constraint rules for I/O requests from application programs and system commands such as the INZPFM command.

Foreign Key Enforcement

The delete and update rules specied at constraint creation apply to parent key changes. To maintain referential integrity, the database enforces a no-action rule for foreign key updates and inserts. This rule must be enforced on foreign key updates and inserts to ensure that every non-null foreign key value has a matching parent key value. If a matching parent key does not exist for the new foreign key value, a referential constraint violation is returned and the dependent record is not inserted or updated. See Chapter 9. Handling Database File Errors in a Program for more information.

Parent Key Enforcement

This section explains how the database processes parent key updates and deletes based on the rules. The unique attribute of a parent key is enforced on all parent le I/O.

Delete Rules
When a record is deleted from a parent le, a check is performed to determine if there are any dependent records (matching non-null foreign key values) in the dependent le. If any dependent records are found, the action taken is dictated by the delete rule: v No Actionif any dependent records are found, a constraint violation is returned and no records are deleted. v Cascadedependent records that are found will be deleted from the dependent le. v Set Nullnull capable elds in the foreign key are set to null in every dependent record that is found. v Set Defaultall elds of the foreign key are set to their default value when the matching parent key is deleted. v RestrictSame as no action except that enforcement is immediate.

246

OS/400 DB2 for AS/400 Database Programming V4R3

If part of the delete rule enforcement fails, the entire delete operation fails and all associated changes are rolled back. For example, a delete cascade rules causes the database to delete ten dependent records but a system failure occurs while deleting the last record. The database will not allow deletion of the parent key and the deleted dependent records are re-inserted. If a referential constraint enforcement causes a change to a record, the associated journal entry will have an indicator value noting the record change was caused by a referential constraint. For example, a dependent record deleted by a delete cascade rule will have a journal entry indicator indicating the record change was generated during referential constraint enforcement. See the Backup and Recovery book for more information on journal entries and indicators.

Update Rules
When a parent key is updated in a parent le, a check is performed to determine if there are any dependent records (matching non-null foreign values) in the dependent le. If any dependent records are found, the action taken is dictated by the update rule specied for the constraint relationship: v No Actionif any dependent records are found, a constraint violation is returned and no records are updated. v Restrictsame as no action except enforcement is immediate. See Chapter 9. Handling Database File Errors in a Program for more information.

Constraint States
A le can be in one of three constraint states. In two of the states, the constraint can be enabled or disabled. Figure 20 on page 248 shows the relationship between these states. v Non-constraint relationship state. No referential constraint exists for a le in this state. If a constraint relationship once existed for the le, all information about it has been removed. v Dened state. A constraint relationship is dened between a dependent and a parent le. It is not necessary to create the member in either le to dene a constraint relationship. In the dened state, the constraint can be: Dened/enabled. A dened/enabled constraint relationship is for denition purposes only. The rules for the constraint are not enforced. A constraint in this state remains enabled when it goes to the established state. Dened/disabled. A dened constraint relationship that is disabled is for denition purposes only. The rules for the constraint are not enforced. A constraint in this state remains disabled when it goes to the established state. v Established state. The dependent le has a constraint relationship with the parent le. A constraint will be established only if the attributes match between the foreign and parent key. Members must exist for both les. In the established state, the constraint can be: Established/enabled. An established constraint relationship that is enabled causes the database to enforce referential integrity. Established/disabled. An established constraint relationship that is disabled directs the database to not enforce referential integrity.

Chapter 16. Referential Integrity

247

 Non-Constraint Relationship State Defined/ Defined/ Enabled State Disabled State Established/ Established/ Enabled State Disabled State

Figure 20. Referential Integrity State Diagram

Check Pending
Check pending is the condition of a constraint relationship when potential mismatches exist between parent and foreign keys. When the system determines that referential integrity may have been violated, the constraint relationship is marked as check pending. For example: v A restore operation where only data in the dependent le is restored and this data is no longer synchronized (a foreign key does not have a parent) with the parent le on the system. v A system failure allowed a parent key value to be deleted when a matching foreign key exists. This can only occur when the dependent and parent les are not journaled. v A foreign key value does not have a corresponding parent key value. This can happen when you add a referential constraint to existing les that have never before been part of a constraint relationship (see Check Pending and the ADDPFCST Command on page 249). Check pending status is either *NO or *YES. When this book says a relationship is in check pending, it always means check pending *YES. Check pending applies only to constraints in the established state. An established/enabled constraint can have a check pending status of *YES or *NO. To get a constraint relationship out of check pending, you must disable the relationship, correct the key (foreign, parent, or both) data, and then re-enable the constraint. The database will then re-verify the constraint relationship. When a relationship is in check pending, the parent and dependent les are in a situation that restricts their use. The parent le I/O restrictions are different than the dependent le restrictions. Check pending restrictions do not apply to constraints that are in the established/disabled state (which are always in check pending status).

248

OS/400 DB2 for AS/400 Database Programming V4R3

Dependent File Restrictions in Check Pending

A dependent le in a constraint relationship that is marked as check pending cannot have any le I/O operations performed on it. The le mismatches between the dependent and parent les must be corrected and the relationship taken out of check pending before I/O operations are allowed. Reading of records from such a le is not allowed because the user or application may not be aware of the check pending status and the constraint violation.

Parent File Restrictions in Check Pending

The parent le of a constraint relationship marked as check pending can be opened but is limited in the types of I/O allowed: v Read is allowed v Insert is allowed v Delete is not allowed v Update is not allowed

Check Pending and the ADDPFCST Command

The ADDPFCST command causes the system to verify that every non-null foreign key value has a matching parent key value (see Verifying Referential Constraints on page 245). If the database marks the newly created constraint relationship as check pending, the constraint is disabled so the data can be corrected. Once the data has been corrected, the constraint should be re-enabled so the database can again check that each record in the dependent le meets the constraint denition. You can identify the records that are in violation of the constraint with the Display Check Pending Constraint (DSPCPCST) command. In this circumstance with very large numbers of records, the DSPCPCST command can also take a long time to process.

Examining Check Pending Constraints

The Display Check Pending Constraints (DSPCPCST) command displays or prints the dependent records (or foreign key values) that caused the constraint relationship to be marked as check pending. Before using this command, use the Change Physical File Constraint (CHGPFCST) command to disable the constraint. This command may take a long time when the associated les have a large number of records. Figure 17 on page 239 is a sample of how the DSPCPCST command shows the records in check pending.

Enabling and Disabling a Constraint

The Change Physical File Constraint (CHGPFCST) command enables or disables one or more referential constraint relationships. Always specify the dependent le when changing a constraint; you cannot disable or enable a constraint by specifying the parent le. You must have a minimum of object management authority (or ALTER privilege) to the dependent le to enable or disable a constraint.

Chapter 16. Referential Integrity

249

While a constraint is being enabled or disabled, the parent and dependent les are locked, both members are locked, and both access paths are locked. The locks are removed when the enable or disable is complete. Attempting to enable an enabled constraint or disable a disabled constraint does nothing but cause the issuance of an informational message. An established/disabled or check pending constraint relationship can be enabled. The enabling causes re-verication of the constraint. If verication nds mismatches between the parent and foreign keys, the constraint is marked as check pending. Disabling a constraint relationship allows all le I/O operations for both the parent and the dependent, providing the user has the correct authority. The entire infrastructure of the constraint remains. The parent key and foreign key access paths are still maintained. However, there is no referential enforcement performed for the two les in the disabled relationship. All remaining enabled constraints are still enforced. Disabling a constraint can allow le I/O operations in performance critical situations to run faster. Always consider the trade-off in this kind of a situation. The le data can become referentially invalid and the database will eventually take the time to reverify the relationship after the constraint is enabled again. Note: Users and applications must be cautious when modifying les with a constraint relationship in the established/disabled state. Relationships can be violated and not detected until the constraint is re-enabled. The Allocate Object (ALCOBJ) command can allocate (lock) les while a constraint relationship is disabled. This allocation prevents others from changing the les while this referential constraint relationship is disabled. A lock for exclusive use should be requested so that other users can read the les. Once the constraint is enabled again, the Deallocate Object (DLCOBJ) command unlocks the les. When you enable or disable multiple constraints, they are processed sequentially. If a constraint cannot be modied, you receive a diagnostic message and function proceeds to the next constraint in the list. When all constraints have been processed, you receive a completion message listing the number of constraints modied.

Removing a Constraint
The Remove Physical File Constraint (RMVPFCST) command removes a constraint. The full impact of the RMVPFCST command depends on what constraint you are removing and certain conditions surrounding the constraint. With the CST parameter, you can specify to remove: v All constraints CST(*ALL) associated with a le v A specic referential constraint CST(constraint-name) v Referential or check constraints in check pending (described in Constraint States on page 247) CST(*CHKPND) With the TYPE parameter, you can specify the type of constraint to remove:

250

OS/400 DB2 for AS/400 Database Programming V4R3

v All types: TYPE(*ALL) All constraints for CST(*ALL) All constraints in check pending for CST(*CHKPND) The named constraint for CST(constraint-name) v Referential constraints: TYPE(*REFCST) All referential constraints for CST(*ALL) All referential constraints in check pending for CST(*CHKPND) The named referential constraint for CST(constraint-name) v Unique constraints: TYPE(*UNQCST) All unique constraints except the primary key constraint for CST(*ALL) Not applicable for CST(*CHKPND)a unique constraint cannot be in check pending The named unique constraint for CST(constraint-name) v Primary key constraints: TYPE(*PRIKEY) The primary constraint for CST(*ALL) Not applicable for CST(*CHKPND)the primary constraint cannot be in check pending The named primary constraint for CST(constraint-name) v Check constraints: TYPE(*CHKCST) All check constraints for CST(*ALL) All check constraints in check pending for CST(*CHKPND) The named check constraint for CST(constraint-name) When you remove a referential constraint, the associated foreign keys and access paths are removed from the le. The foreign key access path is not removed when it is shared by any user or constraint on the system. If you remove a referential constraint, primary key constraint, or unique constraint and the associated access path is shared by a logical le, the ownership of the shared path is transferred to the logical le.

Other AS/400 Functions Affected by Referential Integrity SQL CREATE TABLE

The SQL CREATE TABLE statement allows you to dene column and table constraints when you create the table. For further information see the DB2 for AS/400 SQL Reference book.

SQL ALTER TABLE

The SQL ALTER TABLE statement allows you add or drop a constraint from an existing SQL table. For further information see the DB2 for AS/400 SQL Reference book.

Add Physical File Member (ADDPFM)

In the case where a constraint relationship is dened between a dependent le and a parent le each having zero members:
Chapter 16. Referential Integrity

251

v If a member is rst added to the parent le, the constraint relationship remains in the dened state. v If a member is then added to the dependent le, the foreign key access path is built, and a constraint relationship is established with the parent.

Change Physical File (CHGPF)

When a constraint relationship exists for a le, there are certain parameters available in the CHGPF command that cannot be changed. The restricted parameters are: MAXMBRS The maximum number of members for a le that has a constraint relationship is one: MAXMBRS(1). CCSID The CCSID of a le that is not associated with a constraint, can be changed. If the le is associated with a constraint, the CCSID can only be changed to 65535.

Clear Physical File Member (CLRPFM)

The CLRPFM command fails when issued for a parent le that contains records and is associated with an enabled referential constraint.

FORTRAN Force-End-Of-Data (FEOD)

The FEOD operation fails when issued for a parent le that is associated with an enabled referential constraint relationship.

Create Duplicate Object (CRTDUPOBJ)

When the CRTDUPOBJ command creates a le any constraints associated with the from-le are included. If the parent le is duplicated either to the same library or to a different library, the system cross reference le is used to locate the dependent le of a dened referential constraint, and an attempt is made to establish the constraint relationship. If the dependent le is duplicated, then the TOLIB is used to determine constraint relationships: v If both the parent and dependent les are in the same library, the referential constraint relationship will be established with the parent le in the TOLIB. v If the parent and dependent les are in different libraries, then the referential constraint relationship of the duplicated dependent le will be established with the original parent le.

Copy File (CPYF)

When the CPYF command creates a new le and the original le has constraints, the constraints are not propagated to the new le. For further information about referential integrity impacts on the CPYF command, see the Data Management book.

252

OS/400 DB2 for AS/400 Database Programming V4R3

Move Object (MOVOBJ)

The MOVOBJ command moves a le from one library to another. An attempt is made to establish any dened referential constraints that may exist for the le in the new library.

Rename Object (RNMOBJ)

The RNMOBJ command renames a le within the same library or renames a library. An attempt is made to established any dened referential constraints that may exist for the renamed le or library.

Delete File (DLTF)

The DLTF command has an optional keyword that species how referential constraint relationships are handled. The RMVCST keyword applies to the dependent le in a constraint relationship. The keyword species how much of the constraint relationship of the dependent le is removed when the parent le is deleted: *RESTRICT If a constraint relationship is dened or established between a parent le and dependent le, the parent le is not deleted and the constraint relationship is not removed. This is the default value. *REMOVE The parent le is deleted and the constraint relationship and denition are removed. The constraint relationship between the parent le and the dependent le is removed. The dependent les corresponding foreign key access path or paths and constraint denition are removed. *KEEP The parent le is deleted and the referential constraint relationship denition is left in the dened state. The dependent les corresponding foreign key access path and constraint denition are not removed.

Remove Physical File Member (RMVM)

When the member of a parent le in a constraint relationship is removed, the constraint relationship is put in the dened state. The foreign key access path and referential constraint denition are not removed. The parent key access path is removed because the parent member was removed, but the parent constraint denition remains at the le level. When the member of a dependent le in a constraint relationship is removed, the constraint relationship is put in the dened state. The parent key access path and constraint denition are not removed. The foreign key access path is removed because the dependent member was removed, but the referential constraint denition is not removed.

Chapter 16. Referential Integrity

253

Save/restore
:p If the parent le is restored either to the same library or to a different library, the system cross reference le is used to locate the dependent le of a dened referential constraint. An attempt is made to establish the constraint relationship. If the dependent le is restored, the TOLIB is used to determine constraint relationships: v If both the parent and dependent les are in the same library, the referential constraint relationship is established with the parent le in the TOLIB. v If the parent and dependent les are in different libraries, the referential constraint relationship of the duplicated dependent le is established with the original parent le. The order of the restore of dependent and parent les within a constraint relationship does not matter (that is, the parent is restored before the dependent or the dependent is restored before the parent); the constraint relationship is established. For further information on save or restore functions, see the Backup and Recovery book.

Referential Constraint Considerations and Limitations

v A parent le must be a physical le. v A parent le can have a maximum of one member, MAXMBR(1). v A dependent le must be a physical le. v A dependent le can have a maximum of one member, MAXMBR(1). v A constraint can be dened when both or either of the dependent and parent les have zero members. A constraint cannot be established unless both les have a member. v A le can have a maximum of one primary key but may have many parent keys. v There is maximum of 300 constraint relations per le. This maximum value is the sum of: The referential constraints whether participating as a parent or a dependent, and whether the constraints are dened or established. The unique constraints. v Only externally described les are allowed in referential constraints. Source les are not allowed. Program described les are not allowed. v Files with insert, update, or delete capabilities are not allowed in *RESTRICT relationships. v Constraint names must be unique in a library. v Constraints cannot be added to les in the QTEMP library.

Constraint Cycles
A constraint cycle is a sequence of constraint relationships in which a descendent of a parent le becomes a parent to the original parent le. Constraint cycles are not prohibited in the DB2 for AS/400 database. However, you are strongly urged to avoid using them.

254

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 17. Triggers

A trigger is a set of actions that are run automatically when a specied change operation is performed on a specied physical database le. The change operation can be an insert, update, or delete high level language statement in an application program. Database users can use triggers to: v Enforce business rules v Validate input data v Generate a unique value for a newly inserted row on different le (surrogate function) v Write to other les for audit trail purposes v Query from other les for cross referencing purposes v Access system functions (for example, print an exception message when a rule is violated) v Replicate data to different les to achieve data consistency The following benets can be realized in customers business environment: v Faster application development: because triggers are stored in the database, the actions performed by triggers do not have to be coded in each database application. v Global enforcement of business rules: a trigger can to be dened once and then reused for any application using the database. v Easier maintenance: if a business policy changes, it is necessary to change only the corresponding trigger program instead of each application program. v Improve performance in client/sever environment: all rules are run in the server before returning the result. On the AS/400 system, a set of trigger actions can be dened in any supported high level language. To use the AS/400 trigger support you must create a trigger program and add it to a physical le. To add trigger to a le, you must: v Identify the physical le to be monitored v Identify the kind of operation to be monitored in the le v Create a high-level language or CL program that performs the desired actions.
Database Change File Operation Physical Update, File Add, or Delete Trigger Program High level language pgm C/COBOL/RPG/ PLI/SQL/...

Figure 21. Triggers

Copyright IBM Corp. 1997, 1998

255

Adding a Trigger to a File

The Add Physical File Trigger (ADDPFTRG) command associates a trigger program with a specic physical le. Once the association exists, the system calls the trigger program when a change operation is initiated against the physical le, a member of the physical le, and any logical le created over the physical le.
| | | | | | | | | |

To add a trigger, you must have the following authorities: v Object management or Alter authority to the le v Read data rights to the le v Corresponding data right relative to trigger event v Execute authority to the les library v Execute authority to the trigger program v Execute authority to the trigger programs library The le must have appropriate data capabilities before you add a trigger: v CRTPF ALWUPD(*NO) conicts with *UPDATE Trigger v CRTPF ALWDLT(*NO) conicts with *DELETE Trigger You can associate a maximum of six triggers to one physical le, one of each of the following: v Before an insert v After an insert v Before a delete v After a delete v Before an update v After an update Each insert, delete or update can call a trigger before the change operation occurs and after it occurs. For example, in Figure 22 on page 257 updating a record in the EMP le, the update operation calls a trigger program before and after the update takes place.

256

OS/400 DB2 for AS/400 Database Programming V4R3

Trigger Program 1 Application (before update) 2 - Validate salary range 1 Update the salary - Validate raise date for row 3 in the 3 - Validate authority to EMP file update this field Trigger Program 2 (after update) 4 - Report to project file and update the budget field 5 - Check the budget range; report problem if the budget is over

Figure 22. Triggers Before and After a Change Operation

Assumptions for Figure 22 All les are opened under the same commitment denition. EMP le has a before update trigger (Trigger Program 1) and an after update trigger (Trigger Program 2). Notes for Figure 22 1. The application tries to update the salary eld for an employee in the EMP le. 2. The system calls the before update trigger before the record is updated. The before update trigger validates all the rules. 3. If the validation fails, the trigger signals an exception informing the system that an error occurred in the trigger program. The system then informs the application that the update operation fails and also rolls back any changes made by the before trigger. In this situation, the after update trigger is not called. 4. If all rules are validated successfully, the trigger program returns normally. The system then does the update operation. If the update operation succeeds, the system calls the after update trigger to perform the post update actions. 5. The after update trigger performs all necessary actions and return. If any error occurs in the after update trigger program, the program signals an exception to the system. The system informs the application that the update operation fails and all changes made by the both triggers plus the update operation are rolled back.

Removing a Trigger
The Remove Physical File Trigger (RMVPFTRG) command removes the association of le and trigger program. Once you remove the association no action is taken if a change is made to the physical le. The trigger program, however, remains on the system.

Chapter 17. Triggers

257

Displaying Triggers
The Display File Description (DSPFD) command provides a list of the triggers associated with a le. Specify TYPE(*TRG) or TYPE(*ALL) to get this list. The information provided is: v v v v v The The The The The number of trigger programs trigger program names and libraries trigger events trigger times trigger update conditions

Creating a Trigger Program

To add a trigger to a physical le you must supply a trigger program. This is the program specied in the trigger program (PGM) parameter in the Add Physical File Trigger (ADDPFTRG) command. When a user or application issues a change operation on a physical le that has an associated trigger, the change operation calls the appropriate trigger program. The change operation passes two parameters to the trigger program. From these inputs the trigger program can reference a copy of the original and new records. The trigger program must be coded to accept these parameters.

Trigger Program Input Parameters

The parameters are:
Seq Description I/O 1 Trigger buffer, which Input contains the information about the current change operation that is calling this trigger program. 2 Trigger buffer length Input Type CHAR(*)

BINARY(4)

Trigger Buffer Section

The trigger buffer, see Table 13 on page 259, has two logical sections, a static and a variable: v The static section contains: A trigger template that contains the physical le name, member name, trigger event, trigger time, commit lock level, and CCSID of the current change record and relative record number. Offsets and lengths of the record areas and null byte maps. This section occupies (in decimal) offset 0 through 95. v The variable section contains: Areas for the old record, old null byte map, new record, and new null byte map.

258

OS/400 DB2 for AS/400 Database Programming V4R3

Table 13. Trigger Buffer Offset Dec 0 10 20 30 31 32 33 36 40 48 52 56 60 64 68 72 76 80 * * * * Hex 0 A 14 1E 1F 20 21 24 28 30 34 38 3C 40 44 48 4C 50 * * * * Type CHAR(10) CHAR(10) CHAR(10) CHAR(1) CHAR(1) CHAR(1) CHAR(3) BINARY(4) BINARY(4) BINARY(4) BINARY(4) BINARY(4) BINARY(4) BINARY(4) BINARY(4) BINARY(4) BINARY(4) CHAR(16) CHAR(*) CHAR(*) CHAR(*) CHAR(*) Field Physical le name Physical le library name Physical le member name Trigger event Trigger time Commit lock level Reserved CCSID of data Reserved Original record offset Original record length Original record null byte map offset Original record null byte map length New record offset New record length New record null byte map offset New record null byte map length Reserved Original record Original record null byte map New record New record null byte map

Trigger Buffer Field Descriptions

The following list is in alphabetical order by eld.
CCSID of data. The CCSID of the data in the new and the original records. The data is converted to the job CCSID by the database. Commit lock level. The commit lock level of the current application program. The possible values are: 0 1 2 *NONE *CHG *CS
Chapter 17. Triggers

259

*ALL

New record. A copy of the record that is being inserted or updated in a physical le as a result of the change operation. The new record only applies to the insert or update operations. New record length. The maximum length is 32766 bytes. New record null byte map. This structure contains the NULL value information for each eld of the new record. Each byte represents one eld. The possible values for each byte are: 0 1 Not NULL NULL

New record offset. The location of the new record. The offset value is from the beginning of the trigger buffer. This eld is not applicable if the new value of the record does not apply to the change operation, for example, a delete operation. New record null byte map length. The length is equal to the number of elds in the physical le. New record null byte map offset. The location of the null byte map of the new record. The offset value is from the beginning of the trigger buffer. This eld is not applicable if the new value of the record does not apply to the change operation, for example, a delete operation. Original record. A copy of the original physical record before being updated or deleted. The original record only applies to update and delete operations. Original record length. The maximum length is 32766 bytes. Original record null byte map. This structure contains the NULL value information for each eld of the original record. Each byte represents one eld. The possible values for each byte are: 0 1 Not NULL NULL

Original record null byte map length. The length is equal to the number of elds in the physical le. Original record null byte map offset. The location of the null byte map of the original record. The offset value is from the beginning of the trigger buffer. This eld is not applicable if the original value of the record does not apply to the change operation, for example, an insert operation. Original record offset. The location of the original record. The offset value is from the beginning of the trigger buffer. This eld is not applicable if the original value of the record does not apply to the change operation; for example, an insert operation. Physical le library name. The name of the library in which the physical le resides. Physical le member name. The name of the physical le member. Physical le name. The name of the physical le being changed. Relative Record Number. The relative record number of the record to be updated or deleted (*BEFORE triggers) or the relative record number of the record that was inserted, updated, or deleted (*AFTER triggers). Trigger event. The event that caused the trigger program to be called. The possible values are: 1 2 3 Insert operation Delete operation Update operation

Trigger time. Species the time, relative to the change operation on the physical le, when the trigger program is called. The possible values are: 1 After the change operation

260

OS/400 DB2 for AS/400 Database Programming V4R3

Before the change operation

Trigger Program Coding Guidelines and Usages

v A trigger program can be a high level language, SQL, or CL program. v A trigger program cannot include the following commands, statements, and operations. If they are used, an exception is returned. The COMMIT operation is not allowed for the commitment denition associated with the insert, update, or delete operation that called the trigger. A COMMIT operation IS allowed for any other commitment denition in the job. The ROLLBACK operation is not allowed for the commitment denition associated with the insert, update, or delete operation that called the trigger. A ROLLBACK operation IS allowed for any other commitment denition in the job. The SQL CONNECT, DISCONNECT, SET CONNECTION, and RELEASE statements ARE NOT allowed. The ENDCMTCTL CL command is not allowed for the commitment denition associated with the insert, update, or delete operation that called the trigger. An ENDCMTCTL CL command IS allowed for any other commitment denition in the job. An attempt to add a local API commitment resource (QTNADDCR) to the same commitment denition associated with the insert, update, or delete operation that called the trigger. An attempt to do any I/O to a le that has been opened by a trigger program with *SHARE and is the le that caused the trigger program to be called. v The invoked trigger program can use the same commitment denition as the insert, update, or delete operation that called the trigger and that already has an existing remote resource. However, if the trigger program fails and signals an escape message, and any remote resource for an AS/400 location that is at a pre-Version 3 Release 2 level or for a non-AS/400 location was updated during the non-primary commit cycle, then the entire transaction is put in a rollback-required state. The trigger program can add a remote resource to the commitment denition associated with the insert, update, or delete operation that called the trigger. This allows for LU62 remote resources (protected conversation) and DFM remote resources (DDM le open), but not DRDA remote resources. If a failure occurs when changing a remote resource from a trigger program, the trigger program must end by signalling an escape message. This allows the system to ensure that the entire transaction, for all remote locations, is properly rolled back. If the trigger program does not end with an escape message, the databases on the various remote locations may become inconsistent. v A commit lock level of the application program is passed to the trigger program. It is recommended that the trigger program run under the same lock level as the application program. v The trigger program and application program may run in the same or different activation groups. It is recommended that the trigger program be compiled with ACTGRP(*CALLER) to achieve consistency between the trigger program and the application program. v A trigger program can call other programs or can be nested (that is, a statement in a trigger program causes the calling of another trigger program.) In addition, a trigger program may be called recursively by itself. The maximum trigger

Chapter 17. Triggers

261

nested level for insert and update is 200. When the trigger program runs under commitment control, the following situations will result in an error. Any update of the same record that has already been changed by the change operation or by an operation in the trigger program. Produce conicting operations on the same record within one change operation. For example, a record is inserted by the change operation and then deleted by the trigger program. Notes: 1. If the change operation is not running under commitment control, the change operation is always protected. However, updating the same record within the trigger program will not be monitored. 2. The allowing of repeated changes when running under commitment control are controlled by the ALWREPCHG(*NO|*YES) parameter of the Add Physical File Trigger (ADDPFTRG) command. Changing from the default value to ALWREPCHG(*YES) allows the same record or updated record associated with the trigger program to be repeatedly changed. v The Allow Repeated Change ALWREPCHG(*YES) parameter on the Add Physical File Trigger (ADDPFTRG) command also affects trigger programs dened to be called before insert and update database operations. If the trigger program updates the new record in the trigger buffer and ALWREPCHG(*YES) is specied, the modied new record image is used for the actual insert or update operation on the associated physical le. This option can be helpful in trigger programs that are designed for data validation and data correction. You should be aware that because the trigger program receives physical le record images (even for logical les), the trigger program is allowed to change any eld of that record image. v The trigger program is called for each row that is changed in the physical le. v If the physical le or the dependent logical le is opened for SEQONLY(*YES), and the physical le has a trigger program associated with it, the system changes the open to SEQONLY(*NO) so it can call the trigger program for each row that is changed.

Trigger Program and Commitment Control

Everything about COMMIT in the following sections also applies to ROLLBACK.

Trigger and Application Program Run Under Commitment Control

When the trigger program and the application program run under the same commitment denition, a failure of the trigger program causes the rollback of all statements that are associated with the trigger program. This includes any statement in a nested trigger program. The originating change operation is also rolled back. This requires the trigger program to signal an exception when it encounters an error. When the trigger program and the application program run under different commitment denitions, the COMMIT statements in the application program only affect its own commitment denition. The programmer must commit the changes in the trigger program by issuing the COMMIT statement.

262

OS/400 DB2 for AS/400 Database Programming V4R3

Trigger or Application Program Not Run Under Commitment Control

If both programs do not run under commitment control, any error in a trigger program leaves les in the state that exists when the error occurs. No roll back occurs. If the trigger program does not run under commitment control and the application program does, the COMMIT statement in the application program commits only the changes done by the application program. If the application program does not run under commitment control and the trigger program does, all changes from the trigger program are committed when either: v a commit operation is performed in the trigger program. v the activation group ends. In the normal case, an implicit commit is performed when the activation group ends. However, if an abnormal system failure occurs, a rollback is performed. Any program that is not running under commitment control potentially has data integrity problems. It is the users responsibility to maintain the data integrity if there is a change statement in the program.

Trigger Program Error Messages

If a failures occurs while the trigger program is running, it must signal an appropriate escape message before exiting. Otherwise, the application assumes the trigger program ran successfully. The message can be the original message that is signalled from the system or a message created by the trigger program creator.

Sample Trigger Programs

This section contains four trigger programs that are triggering by the write, update and delete operations to the ATMTRANS le. These trigger programs are written in ILE C, COBOL/400 and RPG/400. For ILE COBOL and ILE RGP examples, see the DB2/400 Advanced Database Function redbook, GG24-4249. The data structures that are used in this application are illustrated as follows: v ATMTRANS : /* Transaction record */
ATMID ACCTID TCODE AMOUNT CHAR(5) (KEY) /* ATM** machine ID number CHAR(5) /* Account number CHAR(1) /* Transaction code ZONED /* Amount to be deposited or /* withdrawn */ */ */ */ */

v ATMS : /* ATM machine record */

ATMN LOCAT ATMAMT CHAR(5) (KEY) /* ATM machine ID number */ CHAR(2) /* Location of ATM */ ZONED /* Total amount in this ATM */ /* machine */ LOCAT MN MN CA ATMAMT 200.00 500.00 250.00

Table 14. ATMS File ATMN 10001 10002 10003

v ACCTS: /* Accounting record */

Chapter 17. Triggers

263

ACCTN BAL ACTACC

CHAR(5) ZONED CHAR(1)

(KEY) /* Account number /* Balance of account /* Status of Account BAL 100.00 100.00 0.00

*/ */ */ ACTACC A A C

Table 15. ACCTS File ACCTN 20001 20002 20003

The application contains four types of transactions

Application -insert 3 transactions to ATMTRANS -Withdraw $25.00 from ACCTID 20001, ATMID 10001 from ATMTRANS -Withdraw $900.00 from ACCTID 20002, ATMID 10002 from ATMTRANS -Delete ATMID 10003 from ATMTRANS Insert Trigger -Update ATMS -Update ACCTS Update Trigger -If not enough money in ACCTS or ATMS, signal error. -Update ATMS -Update ACCTS

Delete Trigger -Delete ATMID from ATMS -Delete ACCTID from ACCTS

Notes: 1. The application inserts three records into the ATMTRANS le which causes an insert trigger to be invoked. The insert trigger adds the correct amount to the ATMS le and the ACCTS le to reect the changes. 2. The application withdraws $25.00 from account number 20001 and ATM number 10001 which invokes the update trigger. The update trigger subtract $25.00 from the ACCTS and ATMS les. 3. The application withdraws $900.00 from account number 20002 and ATM number 10002 which causes an update trigger to be invoked. The update trigger signals an exception to the application indicating that the transaction fails. 4. The application deletes the ATM number from the ATMTRANS le which causes a delete trigger to be invoked. The delete trigger deletes the corresponding ACCTID from the ACCTS le and ATMID from the ATMS le.

Insert Trigger Written in RPG

* * * * * * Program Name : INSTRG This is an insert trigger for the application file. The application inserts the following three records into the ATMTRANS file. ATMID ACCTID TCODE AMOUNT

264

OS/400 DB2 for AS/400 Database Programming V4R3

1 * * Open the ATMS file and the ACCTS file. * FATMS UF E DISK KCOMIT FACCTS UF E DISK KCOMIT * * DECLARE THE STRUCTURES THAT ARE TO BE PASSED INTO THIS PROGRAM. * IPARM1 DS * Physical file name I 1 10 FNAME * Physical file library I 11 20 LNAME * Member name I 21 30 MNAME * Trigger event I 31 31 TEVEN * Trigger time I 32 32 TTIME * Commit lock level I 33 33 CMTLCK * Reserved I 34 36 FILL1 * CCSID I B 37 400CCSID * Reserved I 41 48 FILL2 * Offset to the original record I B 49 520OLDOFF * length of the original record I B 53 560OLDLEN * Offset to the original record null byte map I B 57 600ONOFF * length of the null byte map I B 61 640ONLEN * Offset to the new record I B 65 680NOFF * length of the new record I B 69 720NEWLEN * Offset to the new record null byte map I B 73 760NNOFF * length of the null byte map I B 77 800NNLEN * Reserved I 81 96 RESV3 * Old record ** not applicable I 97 112 OREC * Null byte map of old record I 113 116 OOMAP * Newly inserted record of ATMTRANS I 117 132 RECORD * Null byte map of new record I 133 136 NNMAP
Chapter 17. Triggers

* * * * * * * * * * * * *

-------------------------------10001 20001 D 100.00 10002 20002 D 250.00 10003 20003 D 500.00 When a record is inserted into ATMTRANS, the system calls this program, which updates the ATMS and ACCTS files with the correct deposit or withdrawal amount. The input parameters to this trigger program are: - TRGBUF : contains trigger information and newly inserted record image of ATMTRANS. - TRGBUF Length : length of TRGBUF.

265

IPARM2 DS I B 1 40LENG ****************************************************************** * SET UP THE ENTRY PARAMETER LIST. ****************************************************************** C *ENTRY PLIST C PARM1 PARM PARM1 C PARM2 PARM PARM2 ****************************************************************** * Use NOFF, which is the offset to the new record, to * get the location of the new record from the first * parameter that was passed into this trigger program. * - Add 1 to the offset NOFF since the offset that was * passed to this program started from zero. * - Substring out the fields to a CHARACTER field and * then move the field to a NUMERIC field if it is * necessary. ****************************************************************** C Z-ADDNOFF O 50 C ADD 1 O ****************************************************************** * - PULL OUT THE ATM NUMBER. ****************************************************************** C 5 SUBSTPARM1:O CATM 5 ****************************************************************** * - INCREMENT "O", WHICH IS THE OFFSET IN THE PARAMETER * STRING. PULL OUT THE ACCOUNT NUMBER. ****************************************************************** C ADD 5 O C 5 SUBSTPARM1:O CACC 5 ****************************************************************** * - INCREMENT "O", WHICH IS THE OFFSET IN THE PARAMETER * STRING. PULL OUT THE TRANSACTION CODE. ****************************************************************** C ADD 5 O C 1 SUBSTPARM1:O TCODE 1 ****************************************************************** * - INCREMENT "O", WHICH IS THE OFFSET IN THE PARAMETER * STRING. PULL OUT THE TRANSACTION AMOUNT. ****************************************************************** C ADD 1 O C 5 SUBSTPARM1:O CAMT 5 C MOVELCAMT TAMT 52 ************************************************************* * PROCESS THE ATM FILE. **************** ************************************************************* * READ THE FILE TO FIND THE CORRECT RECORD. C ATMN DOUEQCATM C READ ATMS 61EOF C END C 61 GOTO EOF * CHANGE THE VALUE OF THE ATM BALANCE APPROPRIATELY. C TCODE IFEQ 'D' C ADD TAMT ATMAMT C ELSE C TCODE IFEQ 'W' C SUB TAMT ATMAMT C ELSE C ENDIF C ENDIF * UPDATE THE ATM FILE. C EOF TAG C UPDATATMFILE C CLOSEATMS ************************************************************* * PROCESS THE ACCOUNT FILE. **************** *************************************************************

266

OS/400 DB2 for AS/400 Database Programming V4R3

* READ THE FILE TO FIND THE CORRECT RECORD. ACCTN DOUEQCACC READ ACCTS 62 EOF2 END 62 GOTO EOF2 * CHANGE THE VALUE OF THE ACCOUNTS BALANCE APPROPRIATELY. C TCODE IFEQ 'D' C ADD TAMT BAL C ELSE C TCODE IFEQ 'W' C SUB TAMT BAL C ELSE C ENDIF C ENDIF * UPDATE THE ACCT FILE. C EOF2 TAG C UPDATACCFILE C CLOSEACCTS * C SETON LR C C C C

After the insertions by the application, the ATMTRANS le contains the following data:
Table 16. ATMTRANS ATMID 10001 10002 10003 Records ACCTID 20001 20002 20003 TCODE D D D AMOUNT 100.00 250.00 500.00

After being updated from the ATMTRANS le by the insert trigger program, the ATMS le and the ACCTS le are contain the following data:
Table 17. ATMS File After Update by Insert Trigger ATMN LOCAT 10001 MN 10002 MN 10003 CA Table 18. ACCTS File After Update by Insert Trigger ACCTN BAL 20001 200.00 20002 350.00 20003 500.00 ATMAMT 300.00 750.00 750.00

ACTACC A A C

Update Trigger Written in COBOL

100 200 700 800 800 1900 1900 1900 1900 1900 1900 1900 1900 1900 1900 1900 IDENTIFICATION DIVISION. PROGRAM-ID. UPDTRG. ********************************************************************** **** Program Name : UPDTRG * ***** * ***** This trigger program is called when a record is updated * ***** in the ATMTRANS file. * ***** * ***** This program will check the balance of ACCTS and * ***** the total amount in ATMS.If either one of the amounts * ***** is not enough to meet the withdrawal, an exception * ***** message is signalled to the application. * ***** If both ACCTS and ATMS files have enough money, this * ***** program will update both files to reflect the changes. * ***** * ***** *
Chapter 17. Triggers

267

1900 1900 1900 1900 1900 1900 1900 1900 1900 2000 2100 2200 2300 2400 2500 2700 2700 2800 3300 3400 3500 3600 3700 3800 3900 4000 4100 4200 4300 4400 4500 4600 4700 4800 4900 5000 5100 5200 5300 5400 5500 5600 5700 5800 5900 6000 6100 6200 6300 6400 6500 6600 7000 7100 7200 7300 7400 7500 7600 7700 7800 7900 8000 8100 8200 8300 8400

***** ATMIDs of 10001 and 10002 will be updated in the ATMTRANS * ***** file with the following data: * ***** * ***** ATMID ACCTID TCODE AMOUNT * ***** -------------------------------* ***** 10001 20001 W 25.00 * ***** 10002 20002 W 900.00 * ***** 10003 20003 D 500.00 * ***** * ******************************************************************* ************************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-AS400. OBJECT-COMPUTER. IBM-AS400. SPECIAL-NAMES. I-O-FEEDBACK IS FEEDBACK-JUNK. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT ACC-FILE ASSIGN TO DATABASE-ACCTS ORGANIZATION IS INDEXED ACCESS IS RANDOM RECORD KEY IS ACCTN FILE STATUS IS STATUS-ERR1. SELECT ATM-FILE ASSIGN TO DATABASE-ATMS ORGANIZATION IS INDEXED ACCESS IS RANDOM RECORD KEY IS ATMN FILE STATUS IS STATUS-ERR2. ************************************************************* * COMMITMENT CONTROL AREA. * ************************************************************* I-O-CONTROL. COMMITMENT CONTROL FOR ATM-FILE, ACC-FILE. ************************************************************* * DATA DIVISION * **************************************************************** DATA DIVISION. FILE SECTION. FD ATM-FILE LABEL RECORDS ARE STANDARD. 01 ATM-REC. COPY DDS-ATMFILE OF ATMS. FD ACC-FILE LABEL RECORDS ARE STANDARD. 01 ACC-REC. COPY DDS-ACCFILE OF ACCTS. ************************************************************* * WORKING-STORAGE SECTION * ************************************************************* WORKING-STORAGE SECTION. 01 STATUS-ERR1 PIC XX. 01 STATUS-ERR2 PIC XX. 01 INPUT-RECORD. COPY DDS-TRANS OF ATMTRANS. 05 OFFSET-NEW-REC 01 NUMBERS-1. 03 NUM1 PIC 9(8) PIC 9(10). BINARY.

268

OS/400 DB2 for AS/400 Database Programming V4R3

8500 03 NUM2 PIC 9(10). 8600 03 NUM3 PIC 9(10). 8700 8800 01 FEEDBACK-STUFF PIC X(500) VALUE SPACES. 8900 7100 ************************************************************* 7200 * MESSAGE FOR SIGNALLING ANY TRIGGER ERROR * 7200 * - Define any message ID and message file in the following* 7200 * message data. * 7300 ************************************************************* 9000 01 SNDPGMMSG-PARMS. 9100 03 SND-MSG-ID PIC X(7) VALUE "TRG9999". 9200 03 SND-MSG-FILE PIC X(20) VALUE "MSGF LIB1 ". 9300 03 SND-MSG-DATA PIC X(25) VALUE "Trigger Error". 9400 03 SND-MSG-LEN PIC 9(8) BINARY VALUE 25. 9500 03 SND-MSG-TYPE PIC X(10) VALUE "*ESCAPE ". 9600 03 SND-PGM-QUEUE PIC X(10) VALUE "* ". 9700 03 SND-PGM-STACK-CNT PIC 9(8) BINARY VALUE 1. 9800 03 SND-MSG-KEY PIC X(4) VALUE " ". 9900 03 SND-ERROR-CODE. 10000 05 PROVIDED PIC 9(8) BINARY VALUE 66. 10100 05 AVAILABLE PIC 9(8) BINARY VALUE 0. 10200 05 RTN-MSG-ID PIC X(7) VALUE " ". 10300 05 FILLER PIC X(1) VALUE " ". 10400 05 RTN-DATA PIC X(50) VALUE " ". 10500 10600 ************************************************************* 10700 * LINKAGE SECTION * 10700 * PARM 1 is the trigger buffer * 10700 * PARM 2 is the length of the trigger buffer * 10800 ************************************************************* 10900 LINKAGE SECTION. 11000 01 PARM-1-AREA. 11100 03 FILE-NAME PIC X(10). 11200 03 LIB-NAME PIC X(10). 11300 03 MEM-NAME PIC X(10). 11400 03 TRG-EVENT PIC X. 11500 03 TRG-TIME PIC X. 11600 03 CMT-LCK-LVL PIC X. 11700 03 FILLER PIC X(3). 11800 03 DATA-AREA-CCSID PIC 9(8) BINARY. 11900 03 FILLER PIC X(8). 12000 03 DATA-OFFSET. 12100 05 OLD-REC-OFF PIC 9(8) BINARY. 12200 05 OLD-REC-LEN PIC 9(8) BINARY. 12300 05 OLD-REC-NULL-MAP PIC 9(8) BINARY. 12400 05 OLD-REC-NULL-LEN PIC 9(8) BINARY. 12500 05 NEW-REC-OFF PIC 9(8) BINARY. 12600 05 NEW-REC-LEN PIC 9(8) BINARY. 12700 05 NEW-REC-NULL-MAP PIC 9(8) BINARY. 12800 05 NEW-REC-NULL-LEN PIC 9(8) BINARY. 12900 05 FILLER PIC X(16). 12000 03 RECORD-JUNK. 12900 05 OLD-RECORD PIC X(16). 12900 05 OLD-NULL-MAP PIC X(4). 12900 05 NEW-RECORD PIC X(16). 12900 05 NEW-NULL-MAP PIC X(4). 13000 13100 01 PARM-2-AREA. 13200 03 TRGBUFL PIC X(2). 13300 ***************************************************************** 13400 ****** PROCEDURE DIVISION * 13500 ***************************************************************** 13600 PROCEDURE DIVISION USING PARM-1-AREA, PARM-2-AREA. 13700 MAIN-PROGRAM SECTION. 13800 000-MAIN-PROGRAM. 14000 OPEN I-O ATM-FILE.
Chapter 17. Triggers

269

14100 14200 14300 14400 14500 14600 14600 14600 14700 14800 14900 15000 15100 15200 15300 15400 15500 15600 15700 15800 15900 16000 16100 16200 16300 16400 16500 16600 16700 16800 17100 17200 17300 17400 17500 17600 17700 17800 17900 18000 18100 18200 18300 18600 18700 18800 18900 19000 19100 19200 19300 19400 19500 19600 19900 20000 20100 20200 20300 20400 20500 20600 20700 20800 20900 21000 21100

OPEN I-O ACC-FILE. MOVE 0 TO BAL. ************************************************************* * SET UP THE OFFSET POINTER AND COPY THE NEW RECORD. * * NEED TO ADD 1 TO THE OFFSET SINCE THE OFFSET IN THE INPUT * * PARAMETER STARTS FROM ZERO. * ************************************************************* ADD 1, NEW-REC-OFF GIVING OFFSET-NEW-REC. UNSTRING PARM-1-AREA INTO INPUT-RECORD WITH POINTER OFFSET-NEW-REC. ************************************************************ * READ THE RECORD FROM THE ACCTS FILE * ************************************************************ MOVE ACCTID TO ACCTN. READ ACC-FILE INVALID KEY PERFORM 900-OOPS NOT INVALID KEY PERFORM 500-ADJUST-ACCOUNT. ************************************************************* * READ THE RECORD FROM THE ATMS FILE. * ************************************************************* MOVE ATMID TO ATMN. READ ATM-FILE INVALID KEY PERFORM 950-OOPS NOT INVALID KEY PERFORM 550-ADJUST-ATM-BAL. CLOSE ATM-FILE. CLOSE ACC-FILE. GOBACK. ******************************************************************* ******************************************************************* ******************************************************************* ******************************************************************* ****** THIS PROCEDURE IS USED IF THERE IS NOT ENOUGH MONEY IN THE **** ****** ACCTS FOR THE WITHDRAWAL. **** ******************************************************************* 200-NOT-ENOUGH-IN-ACC. DISPLAY "NOT ENOUGH MONEY IN ACCOUNT.". CLOSE ATM-FILE. CLOSE ACC-FILE. PERFORM 999-SIGNAL-ESCAPE. GOBACK. ******************************************************************* ****** THIS PROCEDURE IS USED IF THERE IS NOT ENOUGH MONEY IN THE ****** ATMS FOR THE WITHDRAWAL. ******************************************************************* 250-NOT-ENOUGH-IN-ATM. DISPLAY "NOT ENOUGH MONEY IN ATM.". CLOSE ATM-FILE. CLOSE ACC-FILE. PERFORM 999-SIGNAL-ESCAPE. GOBACK. ******************************************************************* ****** THIS PROCEDURE IS USED TO ADJUST THE BALANCE FOR THE ACCOUNT OF ****** THE PERSON WHO PERFORMED THE TRANSACTION. ******************************************************************* 500-ADJUST-ACCOUNT. IF TCODE = "W" THEN IF (BAL < AMOUNT) THEN PERFORM 200-NOT-ENOUGH-IN-ACC

270

OS/400 DB2 for AS/400 Database Programming V4R3

21200 21300 21400 21500 21600 21700 21800 21900 22000 22100 22200 22300 22400 22500 22600 22700 22800 22900 23000 23100 23200 23300 23400 23500 23600 23700 23800 23900 24000 24100 24200 24500 24600 24700 24800 24900 25000 25100 25200 25300 25400 25500 25600 25900 26000 26100 26200 26300 26400 26500 26600 26700 26800 26900 27000 27100 27200 27300 27400 27500 27600 27700 27800 27900 28000

ELSE SUBTRACT AMOUNT FROM BAL REWRITE ACC-REC ELSE IF TCODE = "D" THEN ADD AMOUNT TO BAL REWRITE ACC-REC ELSE DISPLAY "TRANSACTION CODE ERROR, CODE IS: ", TCODE. ******************************************************************* ****** THIS PROCEDURE IS USED TO ADJUST THE BALANCE OF THE ATM FILE *** ****** FOR THE AMOUNT OF MONEY IN ATM AFTER A TRANSACTION. *** ******************************************************************* 550-ADJUST-ATM-BAL. IF TCODE = "W" THEN IF (ATMAMT < AMOUNT) THEN PERFORM 250-NOT-ENOUGH-IN-ATM ELSE SUBTRACT AMOUNT FROM ATMAMT REWRITE ATM-REC ELSE IF TCODE = "D" THEN ADD AMOUNT TO ATMAMT REWRITE ATM-REC ELSE DISPLAY "TRANSACTION CODE ERROR, CODE IS: ", TCODE. ************************************************************ ******* ****** THIS PROCEDURE IS USED IF THERE THE KEY VALUE THAT IS USED IS ** ****** NOT FOUND IN THE ACCTS FILE. ** ******************************************************************* 900-OOPS. DISPLAY "INVALID KEY: ", ACCTN, " ACCOUNT FILE STATUS: ", STATUS-ERR1. CLOSE ATM-FILE. CLOSE ACC-FILE. PERFORM 999-SIGNAL-ESCAPE. GOBACK. ******************************************************************* ****** THIS PROCEDURE IS USED IF THERE THE KEY VALUE THAT IS USED IS ** ****** NOT FOUND IN THE ATM FILE. ** ******************************************************************* 950-OOPS. DISPLAY "INVALID KEY: ", ATMN, " ATM FILE STATUS: ", STATUS-ERR2. CLOSE ATM-FILE. CLOSE ACC-FILE. PERFORM 999-SIGNAL-ESCAPE. GOBACK. ******************************************************************* ****** SIGNAL ESCAPE TO THE APPLICATION ******** ******************************************************************* 999-SIGNAL-ESCAPE. CALL "QMHSNDPM" USING SND-MSG-ID, SND-MSG-FILE, SND-MSG-DATA, SND-MSG-LEN, SND-MSG-TYPE, SND-PGM-QUEUE, SND-PGM-STACK-CNT, SND-MSG-KEY, SND-ERROR-CODE. *DISPLAY RTN-MSG-ID. *DISPLAY RTN-DATA.

Chapter 17. Triggers

271

After being updated from the ATMTRANS le by the update trigger programs, the ATMS and ACCTS les contain the following data. The update to the ATMID 10002 fails because of insufficient amount in the account.
Table 19. ATMS File After Update by Update Trigger ATMN LOCAT 10001 MN 10002 MN 10003 CA Table 20. ACCTS File After Update by Update Trigger ACCTN BAL 20001 175.00 20002 350.00 20003 500.00 ATMAMT 275.00 750.00 750.00

ACTACC A A C

Delete Trigger Written in ILE C

/**************************************************************/ /* Program Name - DELTRG */ /* This program is called when a delete operation occurs in */ /* the ATMTRANS file. */ /* */ /* This program will delete the records from ATMS and ACCTS */ /* based on the ATM ID and ACCT ID that are passed in from */ /* the trigger buffer. */ /* */ /* The application will delete ATMID 10003 from the ATMTRANS */ /* file. */ /* */ /**************************************************************/ #include <stdio.h> #include <stdlib.h> #include <recio.h> #include "applib/csrc/msghandler" /* message handler include */ #include "qsysinc/h/trgbuf" /* trigger buffer include without*/ /* old and new records */ Qdb_Trigger_Buffer *hstruct; /* pointer to the trigger buffer */ char *datapt; #define KEYLEN 5 /**************************************************************/ /* Need to define file structures here since there are non*/ /* character fields in each file. For each non-character */ /* field, C requires boundary alignment. Therefore, a _PACKED */ /* struct should be used in order to access the data that */ /* is passed to the trigger program. */ /* */ /**************************************************************/ /** record area for ATMTRANS _Packed struct rec { char atmid[5]; char acctid[5]; char tcode[1]; char amount[5]; } oldbuf, newbuf; /** record area for ATMS _Packed struct rec1{ char atmn[5]; char locat[2]; char atmamt[9]; **/

**/

272

OS/400 DB2 for AS/400 Database Programming V4R3

} atmfile; /** record area for ACCTS _Packed struct rec2{ char acctn[5]; char bal[9]; char actacc[1]; } accfile; **/

/********************************************************************/ /********************************************************************/ /* Start of the Main Line Code. ************************************/ /********************************************************************/ /********************************************************************/ main(int argc, char **argv) { _RFILE *out1; /* file pointer for ATMS */ _RFILE *out2; /* file pointer for ACCTS */ _RIOFB_T *fb; /* file feedback pointer */ char record[16]; /* record buffer */ _FEEDBACK fc; /* feedback for message handler */ _HDLR_ENTRY hdlr = main_handler; /********************************/ /* active exception handler */ /********************************/ CEEHDLR(&hdlr, NULL, &fc);; /********************************/ /* ensure exception handler OK */ /********************************/ if (fc.MsgNo != CEE0000) { printf("Failed to register exception handler.\n"); exit(99); } /* set pointer to the input parameter */ hstruct = (Qdb_Trigger_Buffer *)argv[1]; datapt = (char *) hstruct; /* Copy old and new record from the input parameter */

if ((strncmp(hstruct ->trigger_event,"2",1)== 0)|| /* delete event */ (strncmp(hstruct -> trigger_event,"3",1)== 0)) /* update event */ { obufoff = hstruct ->old_record_offset; memcpy(&oldbuf,datapt+obufoff,; hstruct->old_record_len); } if ((strncmp(hstruct -> trigger_event,"1",1)== 0) || /* insert event */ (strncmp(hstruct -> trigger_event,"3",1)== 0)) /* update event */ { nbufoff = hstruct ->new_record_offset; memcpy(&newbuf,datapt+nbufoff,; hstruct->new_record_len); } /*****************************************************/ /* Open ATM and ACCTS files */ /* */ /* Check the application's commit lock level. If it */ /* runs under commitment control, then open both */ /* files with commitment control. Otherwise, open */ /* both files without commitment control. */ /*****************************************************/ if(strcmp(hstruct->commit_lock_level,"0") == 0) /* no commit { if ((out1=_Ropen("APPLIB/ATMS","rr+")) == NULL) { printf("Error opening ATM file"); exit(1);

*/

Chapter 17. Triggers

273

} else /* with commitment control */ { if ((out1=_Ropen("APPLIB/ATMS","rr+,commit=Y")) == NULL) { printf("Error opening ATMS file"); exit(1); } if ((out2=_Ropen("APPLIB/ACCTS","rr+,commit=Y")) == NULL) { printf("Error opening ACCTS file"); exit(1); } } /* Delete the record based on the input parameter */ fb =_Rlocate(out1,&oldbuf.atmid,KEYLEN,__DFT); if (fb->num_bytes != 1) { printf("record not found in ATMS\n"); _Rclose(out1); exit(1); } _Rdelete(out1); /* delete record from ATMS */ _Rclose(out1); fb =_Rlocate(out2,&oldbuf.acctid,KEYLEN,__DFT); if (fb->num_bytes != 1) { printf("record not found in ACCOUNTS\n"); _Rclose(out2); exit(1); } _Rdelete(out2); /* delete record from ACCOUNTS _Rclose(out2); } /* end of main */

} if ((out2=_Ropen("APPLIB/ACCTS","rr+")) == NULL) { printf("Error opening ACCTS file"); exit(1); }

*/

After the deletion by the application, the ATMTRANS le contains the following data:
Table 21. ATMTRANS ATMID 10001 10002 Records ACCTID 20001 20002 TCODE W W AMOUNT 25.00 900.00

After being deleted from the ATMTRANS le by the delete trigger program, the ATMS le and the ACCTS le are contain the following data:
Table 22. ATMS File After Update by Delete Trigger ATMN LOCAT 10001 MN 10002 MN ATMAMT 275.00 750.00

274

OS/400 DB2 for AS/400 Database Programming V4R3

Table 23. ACCTS File After Update by Delete Trigger ACCTN BAL 20001 175.00 20002 350.00

ACTACC A A

/******************************************************************/ /* INCLUDE NAME : MSGHANDLER */ /* */ /* DESCRIPTION : Message handler to signal an exception message*/ /* to the caller of this trigger program. */ /* */ /* Note: This message handler is a user defined routine. */ /* */ /******************************************************************/ #include <stdio.h> #include <stdlib.h> #include <recio.h> #include <leawi.h> #pragma linkage (QMHSNDPM, OS) void QMHSNDPM(char *, void *, void *, int, char *, char *, int, void *, void *, ...); Message identifier */ Qualified message file name */ Message data or text */ Length of message data or text */ Message type */ Call message queue */ Call stack counter */ Message key */ Error code */ Optionals: length of call message queue name Call stack entry qualification display external messages screen wait time */ /*********************************************************************/ /******** This is the start of the exception handler function. */ /*********************************************************************/ void main_handler(_FEEDBACK *cond, _POINTER *token, _INT4 *rc, _FEEDBACK *new) { /****************************************/ /* Initialize variables for call to */ /* QMHSNDPM. */ /* User defines any message ID and */ /* message file for the following data */ /****************************************/ char message_id[7] = "TRG9999"; char message_file[20] = "MSGF LIB1 "; char message_data[50] = "Trigger error "; int message_len = 30; char message_type[10] = "*ESCAPE "; char message_q[10] = "_C_pep "; int pgm_stack_cnt = 1; char message_key[4]; /****************************************/ /* Declare error code structure for */ /* QMHSNDPM. */ /****************************************/ struct error_code { int bytes_provided; int bytes_available; char message_id[7]; } error_code; error_code.bytes_provided = 15; /****************************************/
Chapter 17. Triggers

/* /* /* /* /* /* /* /* /* /*

275

*rc = CEE_HDLR_RESUME;

/* Set the error handler to resume and */ /* mark the last escape message as */ /* handled. */ /****************************************/ /****************************************/ /* Send my own *ESCAPE message. */ /****************************************/

/****************************************/ /* Check that the call to QMHSNDPM */ /* finished correctly. */ /****************************************/ if (error_code.bytes_available != 0) { printf("Error in QMHOVPM : %s\n", error_code.message_id); } } /****************************************************************/ /* INCLUDE NAME : TRGBUF */ /* */ /* DESCRIPTION : The input trigger buffer structure for the */ /* user's trigger program. */ /* */ /* LANGUAGE : C/400 */ /* resides in QSYSINC/H */ /* */ /****************************************************************/ /****************************************************************/ /* Note: The following type definition only defines the fixed */ /* portion of the format. The data area of the original */ /* record, null byte map of the original record, the */ /* new record, and the null byte map of the new record */ /* is varying length and immediately follows what is */ /* defined here. */ /****************************************************************/ typedef _Packed struct Qdb_Trigger_Buffer { char file_name[10]; char library_name[10]; char member_name[10]; char trigger_event[1]; char trigger_time[1]; char commit_lock_level[1]; char resevered[3]; int data_area_ccsid; char resevered]8]; int old_record_offset; int old_record_len; int old_record_null_byte_map; int old_record_null_byte_map_len; int new_record_offset; int new_record_len; int new_record_null_byte_map; int new_record_null_byte_map_len; } Qdb_Trigger_Buffer;

QMHSNDPM(message_id, &message_file, &message_data, message_len, message_type, message_q, pgm_stack_cnt, &message_key, &error_code );

276

OS/400 DB2 for AS/400 Database Programming V4R3

Other AS/400 Functions Impacted by Triggers Save/Restore Base File (SAVOBJ/RSTOBJ)

v The Save/Restore function will not search for the trigger program during save/restore time. It is the users responsibility to manage the program. During run-time, if the trigger program has not been restored, a hard error with the trigger program name, physical le name, and trigger event is returned. v If the entire library (*ALL) is saved and the physical le and all trigger programs are in the same library and they are restored in a different library, then all the trigger program names are changed in the physical le to reect the new library.

Save/Restore Trigger Program (SAVOBJ/RSTOBJ)

v If the trigger program is restored in a different library, the change operation fails because the trigger program is not found in the original library. A hard error with the trigger program name, physical le name, and trigger event information are returned. There are two ways to recover in this situation: Restore the trigger program to the same library Create a new trigger program with the same name in the new library

Delete File (DLTF)

v The association between trigger programs and a deleted le are removed. The trigger programs remain on the system.

Copy File (CPYF)

v If a to-le is associated with an insert trigger, each inserted record causes the trigger program to be called. v If a to-le is associated with a delete trigger program and MBROPT(*REPLACE) is specied on the CPYF command, the copy operation fails. v Copy with CREATE(*YES) specied does not propagate the trigger information

Create Duplicate Object (CRTDUPOBJ)

v When a trigger program and the base physical le are originally in the same library: If the CRTDUPOBJ command is specied with OBJ(*ALL), the new trigger program is associated with the new physical le. If either a trigger program or the base physical le is duplicated separately, the new trigger program is still associated with the old physical le. v When the trigger program and the physical le are originally in different libraries: The duplicate trigger program is associated with the same physical le as the original trigger program. Even though the physical le is duplicated to the same new library, the duplicated trigger program is still associated with the original physical le.

Clear Physical File Member (CLRPFM)

v If the physical le is associated with a delete trigger, the CLRPFM operation fails.
Chapter 17. Triggers

277

Initialize Physical File Member (INZPFM)

v If the physical le is associated with an insert trigger, the INZPFM operation fails.

FORTRAN Force-End-Of-Data (FEOD)

v If the physical le is associated with a delete trigger, the FEOD operation fails.

Apply Journaled Changes or Remove Journaled Changes (APYJRNCHG/RMVJRNCHG)

v If the physical le is associated with any type of trigger, the APYJRNCHG and RMVJRNCHG operations do not cause the trigger program to be invoked. Therefore, you should be sure to have all the les within the trigger program journaled. Then, when using the APYJRNCHG or RMVJRNCHG commands, be sure to specify all of these les. This insures that all the physical le changes for the application program and the trigger programs are consistent. Note: If any trigger program functions are not related to database les, and cannot be explicitly journaled, you should consider sending journal entries to record relevant information. You can use the Send Journal Entry (SNDJRNE) command or the Send Journal Entrt (QJOSJRNE) API. You will have to use this information when the database les are recovered to ensure consistency.

Recommendations for Trigger Programs

The following are recommended in a trigger program: v Create the program with USRPRF(*OWNER) and do not grant authorities to the trigger program to USER(*PUBLIC). Avoid having the trigger program altered or replaced by other users. The database invokes the trigger program whether or not the user causing the trigger program to run has authority to the trigger program. v Create the program as ACTGRP(*CALLER) if the program is running in an ILE environment. This allows the trigger program to run under the same commitment denition as the application. v Open the le with a commit lock level the same as the applications commit lock level. This allows the trigger program to run under the same commit lock level as the application. v Create the program in the change les library. v Use commit or rollback in the trigger program if the trigger program runs under a different activation group than the application. v Signal an exception if an error occurs or is detected in the trigger program. If an error message is not signalled from the trigger program, the database assumes that the trigger ran successfully. This may cause the user data to end up in an inconsistent state. Trigger programs can be very powerful. Be careful when designing trigger programs that access a system resource like a tape drive. For instance, a trigger program that copies record changes to tape media can be useful, but the program itself cannot detect if the tape drive is ready or if it contains the correct tape. You must take these kind of resource issues into account when designing trigger programs.

278

OS/400 DB2 for AS/400 Database Programming V4R3

The following functions should be carefully considered; they are not recommended in a trigger program: v STRCMTCTL v RCLSPSTG v RCLSRC v CHGSYSLIBL v DLTLICPGM, RSTLICPGM, and SAVLICPGM v SAVLIB SAVACT(*YES) v v v v v Any commands with DKT or TAP Any migration commands The debug program (a security exposure) Any commands related to remote job entry (RJE) Invoking another CL or interactive entrycould reach lock resource limit.

Relationship Between Triggers and Referential Integrity

A physical le can have both triggers and referential constraints associated with it. The running order among trigger actions and referential constraints depends on the constraints and triggers associated with the le. In some cases, the referential constraints are evaluated before an after trigger program is called. This is the case with constraints that specify the RESTRICT rule. In some cases, all statements in the trigger programincluding nested trigger programsare run before the constraint is applied. This is true for NO ACTION, CASCADE, SET NULL, and SET DEFAULT referential constraint rules. When these rules are specied, the system evaluates the les constraints based on the nested results of trigger programs. For example, an application inserts employee records into an EMP le has a constraint and trigger: v The referential constraint species that the department number for an inserted employee record to the EMP le must exist in the DEPT le. v The trigger program, whenever an insert to the EMP le occurs, checks if the department number exist in the DEPT le, and adds the number if it does not exist. When the insertion to the EMP le occurs, the system calls the trigger program rst. If the department number does not exist in the DEPT le, the trigger program inserts the new department number into the DEPT le. Then the system evaluates the referential constraint. In this case, the insertion is successful because the department number exists in the DEPT le. There are some restrictions when both a trigger and referential constraint are dened for the same physical le: v If a delete trigger is associated with a physical le, that le must not be a dependent le in a referential constraint with a delete rule of CASCADE. v If an update trigger is associated with a physical le, no eld in this physical le can be a foreign key in a referential constraint with a delete rule of SET NULL or SET DEFAULT. If failure occurs during either a trigger program or referential constraint validation, all trigger programs associated with the change operation are rolled back if all the les run under the same commitment denition. The referential constraints are
Chapter 17. Triggers

279

guaranteed when all les in the trigger program and the referential integrity network run under the same commitment denition. If the les are opened without commitment control or in a mixed scenario (that is, some les are opened with commitment control and some are not), undesired results may occur. For more information and examples on the interaction between referential constraints and triggers, refer to the redbook DB2/400 Advanced Database Functions GG24-4249. You can use triggers to enforce referential constraints and business rules. For example, you could use triggers to simulate the update cascade constraints on a physical le. However, you would not have the same functional capabilities as provided by the constraints dened with the system referential integrity functions. The following referential integrity advantages may be lost if the constraints are dened with triggers: v Dependent les may contain rows that violate one or more referential constraints that put the constraint into check pending but still allow le operations. v The ability to inform users when a constraint has been placed in check pending. v When an application is running under COMMIT(*NONE) and an error occurs during a cascaded delete, all changes are rolled back by the database. v While saving a le that is associated with a constraint, all dependent les stored in the same library in a database network are saved.

280

OS/400 DB2 for AS/400 Database Programming V4R3

Chapter 18. Database Distribution

DB2 Multisystem, a separately priced feature, provides a simple and direct method of distributing a database le over multiple systems in a loosely-coupled environment. DB2 Multisystem allows users on distributed AS/400 systems real-time query and update access to a distributed database as if it existed totally on their particular system. DB2 Multisystem places new records on the appropriate system based on a user-dened key eld or elds. DB2 Multisystem chooses a system on the basis of either a system-supplied or user-dened hashing algorithm. Query performance is improved by a factor approaching the number of nodes in the environment. For example, a query against a database distributed over four systems runs in approximately one quarter of the time. However, performance can vary greatly when queries involve joins and grouping. Performance is also inuenced by the balance of the data across the multiple nodes. Multisystem runs the query on each system concurrently. DB2 Multisystem can signicantly reduce query time on very large databases. DB2 Multisystem is fully described in DB2 Multisystem for AS/400.

Copyright IBM Corp. 1997, 1998

281

282

OS/400 DB2 for AS/400 Database Programming V4R3

Appendix A. Database File Sizes

The following database le maximums should be kept in mind when designing les on the AS/400 system:
Description Number of bytes in a record Number of elds in a record format Number of key elds in a le Size of key for physical and logical les Size of key for ORDER BY (SQL) and KEYFLD (OPNQRYF) Number of records contained in a le member Number of bytes in a le member Number of bytes in an access path Number of keyed logical les built over a physical le member Number of physical le members in a logical le member Number of members that can be joined Size of a character or DBCS eld Size of a zoned decimal or packed decimal eld Maximum number of constraints per physical le Maximum number of triggers per physical le Maximum number of recursive insert and update trigger calls Maximum Value 32,766 bytes 8,000 elds 120 elds 2000 characters1 10,000 bytes 2,147,483,646 records2 266,757,734,400 bytes3 1,099,511,627,776 bytes3 5 3,686 les 32 members 32 members 32,766 bytes4 31 digits 300 constraints 6 triggers 200

Copyright IBM Corp. 1997, 1998

283

Description :
1

Maximum Value

When a rst-changed-rst-out (FCFO) access path is specied for the le, the maximum value for the size of the key for physical and logical les is 1995 characters. For les with keyed sequence access paths, the maximum number of records in a member varies and can be estimated using the following formula: 2,867,200,000 10 + (.8 x key length) This is an estimated value, the actual maximum number of records can vary signicantly from the number determined by this formula.

Both the number of bytes in a le member and the number of bytes in an access path must be looked at when message CPF5272 is sent indicating that the maximum system object size has been reached. The maximum size of a variable-length character or DBCS eld is 32,740 bytes. DBCS-graphic eld lengths are expressed in terms of characters; therefore, the maximums are 16,383 characters (xed length) and 16,370 characters (variable length). The maximum is 4,294,966,272 bytes if the access path is created with a maximum size of 4 gigabytes (GB), ACCPTHSIZE(*MAX4GB).

These are maximum values. There are situations where the actual limit you experience will be less than the stated maximum. For example, certain high-level languages can have more restrictive limits than those described above. Keep in mind that performance can suffer as you approach some of these maximums. For example, the more logical les you have built over a physical le, the greater the chance that system performance can suffer (if you are frequently changing data in the physical le that causes a change in many logical le access paths). Normally, an AS/400 database le can grow until it reaches the maximum size allowed on the system. The system normally will not allocate all the le space at once. Rather, the system will occasionally allocate additional space as the le grows larger. This method of automatic storage allocation provides the best combination of good performance and effective auxiliary storage space management. If you want to control the size of the le, the storage allocation, and whether the le should be connected to auxiliary storage, you can use the SIZE, ALLOCATE, and CONTIG parameters on the Create Physical File (CRTPF) and the Create Source Physical File (CRTSRCPF) commands. You can use the following formulas to estimate the disk size of your physical and logical les. v For a physical le (excluding the access path): Disk size = (number of valid and deleted records + 1) x (record length + 1) + 12288 x (number of members) + 4096

284

OS/400 DB2 for AS/400 Database Programming V4R3

The size of the physical le depends on the SIZE and ALLOCATE parameters on the CRTPF and CRTSRCPF commands. If you specify ALLOCATE(*YES), the initial allocation and increment size on the SIZE keyword must be used instead of the number of records. v For a logical le (excluding the access path): Disk size = (12288) x (number of members) + 4096 v For a keyed sequence access path the generalized equation for index size, per member, is:

let a = (LimbPageUtilization - LogicalPageHeaderSize) * (LogicalPageHeaderSize - LeafPageUtilization - 2 * NodeSize) let b = NumKeys * (TerminalTextPerKey + 2 * NodeSize) * (LimbPageUtilization - LogicalPageHeaderSize + 2 * NodeSize) + CommonTextPerKey * [ LimbPageUtilization + LeafPageUtilization - 2 * (LogicalPageHeaderSize - NodeSize) ] - 2 * NodeSize * (LeafPageUtilization - LogicalPageHeaderSize + 2 * NodeSize) let c = CommonTextPerKey * [ 2 * NodeSize - CommonTextPerKey - NumKeys * (TerminalTextPerKey + 2 * NodeSize) ]

then NumberLogicalPages = ceil( [ -b - sqrt(b ** 2 - 4 * a * c) ] / (2 * a)) and TotalIndexSize = NumberLogicalPages * LogicalPageSize

This equation is used for both three and four byte indexes by changing the set of constants in the equation as follows:
Constant NodeSize LogicalPageHeaderSize LimbPageUtilization LeafPageUtilization Three-byte Index 3 16 .75 * LogicalPageSize .75 * LogicalPageSize Four-byte Index 4 64 .75 * LogicalPageSize .80 * LogicalPageSize

The remaining constants, CommonTextPerKey and TerminalTextPerKey, are probably best estimated by using the following formulas:

CommonTextPerKey = [ min(max(NumKeys - 256,0),256) + min(max(NumKeys - 256 * 256,0),256 * 256) + min(max(NumKeys - 256 * 256 * 256,0), 256 * 256 * 256) + min(max(NumKeys - 256 * 256 * 256 * 256,0), 256 * 256 * 256 * 256) ] * (NodeSize + 1) / NumKeys TerminalTextPerKey = KeySizeInBytes - CommonTextPerKey

Appendix A. Database File Sizes

285

This should reduce everything needed to calculate the index size to the type of index (i.e. 3 or 4 byte), the total key size, and the number of keys. The estimate should be greater than the actual index size because the common text estimate is minimal. Given this generalized equation for index size, the LogicalPageSize is as follows:
Table 24. LogicalPageSize Values Key Length *MAX4GB (3-byte) LogicalPageSize 1 - 500 4096 bytes 501 - 1000 8192 bytes 1001 - 2000 16384 bytes *MAX1TB (4-byte) LogicalPageSize 8192 bytes 16384 bytes 32768 bytes

The LogicalPageSizes in Table 24 generate the following LimbPageUtilizations:

Key Length 1 - 500 501 - 1000 1001 - 2000 *MAX4GB (3-byte) LimbPageUtilization 3072 bytes 6144 bytes 12288 bytes *MAX1TB (4-byte) LimbPageUtilization 6144 bytes 12288 bytes 24576 bytes

The LogicalPageSizes in Table 24 generate the following LeafPageUtilizations:

Key Length 1 - 500 501 - 1000 1001 - 2000 *MAX4GB (3-byte) LeafPageUtilization 3072 bytes 6144 bytes 12288 bytes *MAX1TB (4-byte) LeafPageUtilization 6554 bytes 13107 bytes 26214 bytes

Then to simplify the generalized equation for index size, let:

CommonTextPerKey = 0 which would cause: TerminalTextPerKey = KeySizeInBytes b = NumKeys * (KeySizeInBytes + 2 * NodeSize) * (LimbPageUtilization - LogicalPageHeaderSize + 2 * NodeSize) - 2 * NodeSize * (LeafPageUtilization - LogicalPageHeaderSize + 2 * NodeSize) c = 0 NumberLogicalPages = ceil( [ -b - sqrt(b ** 2 ) ] / (2 * a)) = ceil[ (-2 * b) / (2 * a) ] = ceil[ -b/a ]

286

OS/400 DB2 for AS/400 Database Programming V4R3

Examples
A *MAX1TB (4-byte) access path with 120 byte keys and 500,000 records TotalIndexSize would have a TotalIndexSize in bytes as follows:
a = (LimbPageUtilization - LogicalPageHeaderSize) * (LogicalPageHeaderSize - LeafPageUtilization - 2 * NodeSize) = (6144 - 64) * (64 - 6554 - 2 * 4) = 6080 * -6498 = -39,507,840 b = NumKeys * (KeySizeInBytes + 2 * NodeSize) * (LimbPageUtilization - LogicalPageHeaderSize + 2 * NodeSize) - 2 * NodeSize * (LeafPageUtilization - LogicalPageHeaderSize + 2 * NodeSize) = 500,000 * (120 + 2 * 4) * (6144 - 64 + 2 * 4) - 2 * 4 * (6554 - 64 + 2 * 4) = 500,000 * 128 * 6088 - 8 * 6498 = 3.896319e+11 NumberLogicalPages = ceil[ -b/a ] = ceil[ -3.896319e+11/-39507840 ] = 9863 TotalIndexSize = NumberLogicalPages * LogicalPageSize = 9863 * 8192 = 80,797,696 bytes

The equation for index size in previous versions of the operating system would produce the following result:
TotalIndexSize = (number of keys) * (key length + 8) * (0.8) * (1.85) + 4096 = (NumKeys) * (KeySizeInBytes + 8) * (0.8) * (1.85) + 4096 = 500000 * 128 * .8 * 1.85 + 4096 = 94,724,096

This estimate can differ signicantly from your le. The keyed sequence access path depends heavily on the data in your records. The only way to get an accurate size is to load your data and display the le description. The following is a list of minimum le sizes:
Description Physical le without a member Physical le with a single member Keyed sequence access path Minimum Size 8192 bytes 20480 bytes 12288 bytes

Note: Additional space is not required for an arrival sequence access path. In addition to the le sizes, the system maintains internal formats and directories for database les. (These internal objects are owned by user prole QDBSHR.) The following are estimates of the sizes of those objects: v For any le not sharing another les format:

Appendix A. Database File Sizes

287

Format size = (96 x number of elds) + 4096 v For les sharing their format with any other le: Format sharing directory size = (16 x number of les sharing the format) + 3856 v For each physical le and each physical le member having a logical le or logical le member built over it: Data sharing directory size = (16 x number of les or members sharing data) + 3856 v For each le member having a logical le member sharing its access path: Access path sharing directory size = (16 x number of les or members sharing access path) + 3856

288

OS/400 DB2 for AS/400 Database Programming V4R3

Appendix B. Double-Byte Character Set (DBCS) Considerations

A double-byte character set (DBCS) is a character set that represents each character with 2 bytes. The DBCS supports national languages that contain a large number of unique characters or symbols (the maximum number of characters that can be represented with 1 byte is 256 characters). Examples of such languages include Japanese, Korean, and Chinese. This appendix describes DBCS considerations as they apply to the database on the AS/400 system.

DBCS Field Data Types

There are two general kinds of DBCS data: bracketed-DBCS data and graphic (nonbracketed) DBCS data. Bracketed-DBCS data is preceded by a DBCS shift-out character and followed by a DBCS shift-in character. Graphic-DBCS data is not surrounded by shift-out and shift-in characters. The application program might require special processing to handle bracketed-DBCS data that would not be required for graphic-DBCS data. The specic DBCS data types (specied in position 35 on the DDS coding form.) are: Entry O E J G Meaning DBCS-open: A character string that contains both single-byte and bracketed double-byte data. DBCS-either: A character string that contains either all single-byte data or all bracketed double-byte data. DBCS-only: A character string that contains only bracketed double-byte data. DBCS-graphic: A character string that contains only nonbracketed double-byte data.

Note: Files containing DBCS data types can be created on a single-byte character set (SBCS) system. Files containing DBCS data types can be opened and used on a SBCS system, however, coded character set identier (CCSID) conversion errors can occur when the system tries to convert from a DBCS or mixed CCSID to a SBCS CCSID. These errors will not occur if the job CCSID is 65535.

DBCS Constants
A constant identies the actual character string to be used. The character string is enclosed in apostrophes and a string of DBCS characters is surrounded by the DBCS shift-out and shift-in characters (represented by the characters < and > in the following examples). A DBCS-graphic constant is preceded by the character G. The types of DBCS constants are: Type Example

Copyright IBM Corp. 1997, 1998

289

DBCS-Only DBCS-Open DBCS-Graphic

<A1A2A3> <A1A2A3>BCD G<A1A2A3>

DBCS Field Mapping Considerations

The following chart shows what types of data mapping are valid between physical and logical les for DBCS elds:
Logical File Data Type DBCSDBCSHexadecimal DBCS- Open Either Only Valid Valid Valid Not valid Valid Valid Valid Valid Valid Valid Not valid Not valid Valid Valid Valid Not valid Valid Valid Valid Valid Not valid Valid Valid Valid Not valid Not valid Valid Valid

Physical File Data Type Character Hexadecimal DBCS-open DBCS-either DBCS-only DBCS-graphic UCS2-graphic

Character Valid Valid Not valid Not valid Not valid Not valid Not valid

DBCSGraphic Not valid Not valid Not valid Not valid Valid Valid Not valid

UCS2Graphic Not valid Not valid Not valid Valid Valid Not valid Valid

DBCS Field Concatenation

When elds are concatenated, the data types can change (the resulting data type is automatically determined by the system). v OS/400 assigns the data type based on the data types of the elds that are being concatenated. When DBCS elds are included in a concatenation, the general rules are: If the concatenation contains one or more hexadecimal (H) elds, the resulting data type is hexadecimal (H). If all elds in the concatenation are DBCS-only (J), the resulting data type is DBCS-only (J). If the concatenation contains one or more DBCS (O, E, J) elds, but no hexadecimal (H) elds, the resulting data type is DBCS open (O). If the concatenation contains two or more DBCS open (O) elds, the resulting data type is a variable-length DBCS open (O) eld. If the concatenation contains one or more variable-length elds of any data type, the resulting data type is variable length. A DBCS-graphic (G) eld can be concatenated only to another DBCS-graphic eld. The resulting data type is DBCS-graphic (G). A UCS2-graphic (G) eld can be concatenated only to another UCS2-graphic eld. The resulting data type is UCS2-graphic (G). v The maximum length of a concatenated eld varies depending on the data type of the concatenated eld and length of the elds being concatenated. If the concatenated eld is zoned decimal (S), its total length cannot exceed 31 bytes. If the concatenated eld is character (A), DBCS-open (O), or DBCS-only (J), its total length cannot exceed 32,766 bytes (32,740 bytes if the eld is variable length).

290

OS/400 DB2 for AS/400 Database Programming V4R3

The length of DBCS-graphic (G) elds is expressed as the number of double-byte characters (the actual length is twice the number of characters); therefore, the total length of the concatenated eld cannot exceed 16,383 characters (16,370 characters if the eld is variable length). v In join logical les, the elds to be concatenated must be from the same physical le. The rst eld specied on the CONCAT keyword identies which physical le is used. The rst eld must, therefore, be unique among the physical les on which the logical le is based, or you must also specify the JREF keyword to specify which physical le to use. v The use of a concatenated eld must be I (input only). v REFSHIFT cannot be specied on a concatenated eld that has been assigned a data type of O or J. Notes: 1. When bracketed-DBCS elds are concatenated, a shift-in at the end of one eld and a shift-out at the beginning of the next eld are removed. If the concatenation contains one or more hexadecimal elds, the shift-in and shift-out pairs are only eliminated for DBCS elds that precede the rst hexadecimal eld. 2. A concatenated eld that contains DBCS elds must be an input-only eld. 3. Resulting data types for concatenated DBCS elds may differ when using The Open Query File (OPNQRYF) command. See Using Concatenation with DBCS Fields through OPNQRYF on page 293 for general rules when DBCS elds are included in a concatenation.

DBCS Field Substring Operations

A substring operation allows you to use part of a eld or constant in a logical le. For bracketed-DBCS data types, the starting position and the length of the substring refer to the number of bytes; therefore, each double-byte character counts as two positions. For the DBCS-graphic (G) data type, the starting position and the length of the substring refer to the number of characters; therefore, each double-byte character counts as one position.

Comparing DBCS Fields in a Logical File

When comparing two elds or a eld and constants, xed-length elds can be compared to variable-length elds as long as the types are compatible. Table 25 describes valid comparisons for DBCS elds in a logical le.
Table 25. Valid Comparisons for DBCS Fields in a Logical File Any CharNumeric acter Any Valid Not Numeric valid Character Not Valid valid HexaNot Valid decimal valid DBCSNot Valid Open valid Hexadecimal Not valid Valid Valid Valid DBCSOpen Not valid Valid Valid Valid DBCSEither Not valid Valid Valid Valid DBCSOnly Not valid Not valid Valid Valid DBCSGraphic Not valid Not valid Not valid Not valid UCS2/UCS-2 Graphic Not valid Not valid Not valid Not valid Time Stamp Not valid Not valid Not valid Not valid

Date Not valid Not valid Not valid Not valid

Time Not valid Not valid Not valid Not valid

Appendix B. Double-Byte Character Set (DBCS) Considerations

291

Table 25. Valid Comparisons for DBCS Fields in a Logical File (continued) Any Numeric Not valid Not valid Not valid Not valid Not valid Not valid Not valid Character Valid Not valid Not valid Not valid Not valid Not valid Not valid HexaDBCSdecimal Open Valid Valid Valid Not valid Not valid Not valid Not valid Not valid Valid Not valid Not valid Not valid Not valid Not valid DBCSEither Valid Valid Not valid Not valid Not valid Not valid Not valid DBCSOnly Valid Valid Not valid Not valid Not valid Not valid Not valid DBCSGraphic Not valid Not valid Valid Not valid Not valid Not valid Not valid UCS2/UCS-2 Graphic Not valid Not valid Not valid Valid Not valid Not valid Not valid Time Stamp Not valid Not valid Not valid Not valid Not valid Not valid Valid

DBCSEither DBCSOnly DBCSGraphic UCS2Graphic Date Time Time Stamp

Date Not valid Not valid Not valid Not valid Valid Not valid Not valid

Time Not valid Not valid Not valid Not valid Not valid Valid Not valid

Using DBCS Fields in the Open Query File (OPNQRYF) Command

This section describes considerations when using DBCS elds in the Open Query File (OPNQRYF) command.

Using the Wildcard Function with DBCS Fields

Use of the wildcard (%WLDCRD) function with a DBCS eld differs depending on whether the function is used with a bracketed-DBCS eld or a DBCS-graphic eld. When using the wildcard function with a bracketed-DBCS eld, both single-byte and double-byte wildcard values (asterisk and underline) are allowed. The following special rules apply: v A single-byte underline refers to one EBCDIC character; a double-byte underline refers to one double-byte character. v A single- or double-byte asterisk refers to any number of characters of any type. When using the wildcard function with a DBCS-graphic eld, only double-byte wildcard values (asterisk and underline) are allowed. The following special rules apply: v A double-byte underline refers to one double-byte character. v A double-byte asterisk refers to any number of double-byte characters.

Comparing DBCS Fields Through OPNQRYF

When comparing two elds or constants, xed length elds can be compared to variable length elds as long as the types are compatible. Table 26 on page 293 describes valid comparisons for DBCS elds through the OPNQRYF command.

292

OS/400 DB2 for AS/400 Database Programming V4R3

Table 26. Valid Comparisons for DBCS Fields through the OPNQRYF Any CharHexaDBCS- DBCS- DBCSNumeric acter decimal Open Either Only Any Valid Not Not Not Not Not Numeric valid valid valid valid valid Character Not Valid Valid Valid Valid Not valid valid HexaNot Valid Valid Valid Valid Valid decimal valid DBCSNot Valid Valid Valid Valid Valid Open valid Not Valid Valid Valid Valid Valid DBCSEither valid DBCSNot Not Valid Valid Valid Valid Only valid valid DBCSNot Not Not Not Not Not Graphic valid valid valid valid valid valid UCS2Not Valid Not Valid Valid Valid Graphic valid valid Date Not Valid Valid Valid Valid Not valid valid Time Not Valid Valid Valid Valid Not valid valid Time Not Valid Valid Valid Valid Not Stamp valid valid

Command DBCSGraphic Not valid Not valid Not valid Not valid Not valid Not valid Valid Valid Not valid Not valid Not valid

UCS2Graphic Not valid Valid Not valid Valid Valid Valid Valid Valid Not valid Not valid Not valid

Date Not valid Valid Valid Valid Valid Not valid Not valid Not valid Valid Not valid Not valid

Time Not valid Valid Valid Valid Valid Not valid Not valid Not valid Not valid Valid Not valid

Time Stamp Not valid Valid Valid Valid Valid Not valid Not valid Not valid Not valid Not valid Valid

Using Concatenation with DBCS Fields through OPNQRYF

When using the Open Query File (OPNQRYF) concatenation function, the OS/400 program assigns the resulting data type based on the data types of the elds being concatenated. When DBCS elds are included in a concatenation, the resulting data type is generally the same as concatenated elds in a logical le, with some slight variations. The following rules apply: v If the concatenation contains one or more hexadecimal (H) elds, the resulting data type is hexadecimal (H). v If the concatenation contains one or more UCS2-graphic elds, the resulting data type is UCS2-graphic. v If all elds in the concatenation are DBCS-only (J), the resulting data type is variable length DBCS-only (J). v If the concatenation contains one or more DBCS (O, E, J) elds, but no hexadecimal (H) or UCS2-graphic elds, the resulting data type is variable length DBCS open (O). v If the concatenation contains one or more variable length elds of any data type, the resulting data type is variable length. v If a DBCS-graphic (G) eld is concatenated to another DBCS-graphic (G) eld, the resulting data type is DBCS-graphic (G).

Appendix B. Double-Byte Character Set (DBCS) Considerations

293

Using Sort Sequence with DBCS

When a sort sequence is specied, no translation of the DBCS data is done. Only SBCS data in DBCS-either or DBCS-open elds is translated. UCS2 data is translated.

294

OS/400 DB2 for AS/400 Database Programming V4R3

Appendix C. Database Lock Considerations

Table 27 summarizes some of the most commonly used database functions and the types of locks they place on database les. The types of locks are explained on the next page.
Table 27. Database Functions and Locks Function Command Add Member ADDPFM, ADDLFM Change File CHGPF, CHGLF Attributes Change Member CHGPFM, CHGLFM Attributes Change Object Owner CHGOBJOWN Check Object CHKOBJ Clear Physical File CLRPFM Member Create Duplicate CRTDUPOBJ Object Create File CRTPF, CRTLF, CRTSRCPF Delete File DLTF Grant/Revoke GRTOBJAUT, Authority RVKOBJAUT Initialize Physical File INZPFM Member Move Object MOVOBJ Open File OPNDBF, OPNQRYF Rebuild Access Path EDTRBDAP, OPNDBF Remove Member RMVM Rename File RNMOBJ Rename Member RNMM Reorganize Physical RGZPFM File Member Restore File RSTLIB, RSTOBJ Save File SAVLIB, SAVOBJ, SAVCHGOBJ :
1

File Lock *EXCLRD *EXCL *SHRRD *EXCL *SHRNUPD *SHRRD *EXCL (new object) *SHRNUPD (object) *EXCL *EXCL *EXCL *SHRRD *EXCL *SHRRD *SHRRD *EXCLRD *EXCL *EXCLRD *SHRRD *EXCL *SHRNUPD1

Member/Data Lock *EXCLRD *EXCLRD

Access Path Lock *EXCLRD *EXCLRD

*EXCLRD3

*EXCLRD

*EXCLRD

*SHRRD *SHRRD *EXCL *EXCL *EXCL *EXCL

*EXCLRD *EXCLRD *EXCLRD *EXCL *EXCL

*SHRNUPD2

For save-while-active, the le lock is *SHRUPD initially, and then the lock is reduced to *SHRRD. See the Backup and Recovery for a description of save-while-active locks for the save commands. For save-while-active, the member/data lock is *SHRRD. The clear does not happen if the member is open in this process or any other process.

2 3

The following table shows the valid lock combinations:

Lock *EXCL1 *EXCL *EXCLRD *SHRUPD *SHRNUPD *SHRRD

Copyright IBM Corp. 1997, 1998

295

Lock *EXCLRD2 *SHRUPD3 *SHRNUPD4 *SHRRD5 :

1

*EXCL

*EXCLRD

*SHRUPD X

*SHRNUPD

X X

*SHRRD X X X X

Exclusive lock (*EXCL). The object is allocated for the exclusive use of the requesting job; no other job can use the object. Exclusive lock, allow read (*EXCLRD). The object is allocated to the job that requested it, but other jobs can read the object. Shared lock, allow read and update (*SHRUPD). The object can be shared either for read or change with other jobs. Shared lock, read only (*SHRNUPD). The object can be shared for read with other jobs. Shared lock (*SHRRD). The object can be shared with another job if the job does not request exclusive use of the object.

Table 28 shows database locking for constraints of a database le, depending on whether the constraint is associated with the parent le (PAR) or the dependent le (DEP).
Table 28. Database Constraint Locks. The numbers in parentheses refer to notes of the table. TYPE OF MEMBER OTHER FUNCTION FILE TYPE FILE (5) (5) FILE ADDPFM (1) DEP *EXCL *EXCL *EXCL ADDPFM (1) PAR *EXCL *EXCL *EXCL ADDPFCST (7) *REFCST *EXCL *EXCL *EXCL ADDPFCST (6) *UNQCST *PRIKEY *EXCL *EXCL *EXCL ADDPFCST *UNIQUE *PRIKEY *EXCL *EXCL RMVM (2) DEP *EXCL *EXCL *EXCL RMVM (2) PAR *EXCL *EXCL *EXCL DLTF (3) DEP *EXCL *EXCL *EXCL DLTF (3) PAR *EXCL *EXCL *EXCL RMVPFCST (7) *REFCST *EXCL *EXCL *EXCL (4) RMVPFCST (6) *UNQCST *PRIKEY *EXCL *EXCL *EXCL RMVPFCST *UNIQUE *PRIKEY *EXCL *EXCL CHGPFCST *EXCL *EXCL *SHRRD at the end OTHER MEMBER *EXCL *EXCL *EXCL *EXCL *EXCL *EXCL *EXCL *EXCL *EXCL *EXCL *EXCL

296

OS/400 DB2 for AS/400 Database Programming V4R3

Table 28. Database Constraint Locks (continued). The numbers in parentheses refer to notes at the end of the table. TYPE OF MEMBER OTHER OTHER FUNCTION FILE TYPE FILE (5) (5) FILE MEMBER Note: 1. If the add of a physical le member will cause a referential constraint to be established. 2. If the remove of a physical le member will cause an established referential constraint to become dened. 3. When deleting a dependent or parent le that has constraints established or dened for the le. 4. When the remove physical le constraint command (RMVPFCST) is invoked for the parent le which has constraints established or dened, the parent and any logical les over the parent le are all locked *EXCL. 5. For referential constraints, the column refers to the dependent le or the dependent member. 6. Unique constraint or primary key constraint is a parent key in a referential constraint where the other le is the dependent le. 7. Other le is the parent le.

Appendix C. Database Lock Considerations

297

298

OS/400 DB2 for AS/400 Database Programming V4R3

Appendix D. Query Performance: Design Guidelines and Monitoring

Overview
This chapter discusses many sections related to programming for optimizing performance of a query application. As a general rule, most of the guidelines can be ignored and the results will still be correct. However, if you apply the guidelines your programs will run more efficiently. Note: The information in this chapter is complex. It may be helpful to experiment with an AS/400 system as you read this chapter to verify some of the information. If one understands how DB2 for AS/400 processes queries, it is easier to understand the performance impacts of the guidelines discussed in this chapter. There are three major components of DB2 for AS/400: 1. DB2 for AS/400 Query Component This component provides a common interface for database query access. See DB2 for AS/400 Query Component on page 300. 2. Data management methods These methods are the algorithms used to retrieve data from the disk. The methods include index usage and record selection techniques. In addition, parallel access methods are available with the DB2 Symmetric Multiprocessing (SMP) for AS/400 operating system feature. See Data Management Methods on page 301. 3. Query optimizer The query optimizer identies the valid techniques which could be used to implement the query and selects the most efficient technique. See The Optimizer on page 325.

Denition of Terms
Understanding the following terms is necessary in order to understand the information in this chapter: Access plan A control structure that describes the actions necessary to satisfy each query request. An access plan contains information about the data and how to extract it. The cursor is a pointer. It references the record to be processed. An I/O area that is opened for every le during the processing of a high-level language (HLL) program.

Cursor Open data path (ODP)

Copyright IBM Corp. 1997, 1998

299

DB2 for AS/400 Query Component

Traditional HLL program I/O statements access data one record at a time. You can use I/0 statements in conjunction with logical les to provide relational operations such as: v v v v Record selection Sequence Join Project

This is often the most efficient manner for data retrieval. Query products are best used when logical les are not available for data retrieval requests, or if functions are required that logical les cannot support, are too difficult to write, or would perform poorly, for example, the distinct, group by, subquery, and like functions. The query products use something more sophisticated to perform these functions. It is done with the access plan in combination with a specialized, high-function query routine called the DB2 for AS/400 query component, which is internal to the OS/400 program. (The DB2 for AS/400 query component should not be confused with the Query for AS/400 licensed program.) The advantage of this function is that, because the query requests are created at run time, there are often fewer permanent access paths than are required for multiple logical les. Some of the programs and functions on the AS/400 system which use the DB2 for AS/400 query component: v OPNQRYF v v v v SQL run-time support Query for AS/400 run-time support Query/38 run-time support Client Access le transfer

v DB2 for AS/400 Query Management v OfficeVision (for document searches) v Performance Tools (for report generation) The difference between the terminology of SQL, Query for AS/400, and Query/38 versus SQL run-time support, Query for AS/400 run-time support, and Query/38 run-time support is that the former group refers to the names of the licensed program. The licensed programs are not required to run each of these, as the run-time support comes with the OS/400 program and not the licensed programs. Figure 23 helps to explain the relationship between the various functions that use the DB2 for AS/400 query component at run time, and the way in which traditional HLL program I/O requests are satised. Note that I/O requests from HLL programs without SQL commands go directly to the database support to retrieve the data. Request from HLL programs that contain SQL commands go through DB2 for AS/400 query component and optimizer. Query product requests call on the DB2 for AS/400 query component, which uses the optimizer before calling the database support to create the ODP to the data. Once an ODP has been created, no difference exists between HLL I/O requests and the I/O requests of these query products. Both send requests for data to the database support.

300

OS/400 DB2 for AS/400 Database Programming V4R3

SQL Query Manager DB2 for OS/400 Query ISQL Management

Query/400

HHL HHL OPNQRYF SQL Query/400 Query/38 PC Support programs programs run-time run-time run-time File Transfer without with SQL SQL commands commands (COBOL, (COBOL, RPG, RPG, etc.) etc.) DB2 for OS/400 query component Optimizer Database Support Machine Interface Licensed Internal Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D A T A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Figure 23. Methods of Accessing AS/400 Data

Data Management Methods

AS/400 data management provides various methods to retrieve data. This section introduces the fundamental techniques used in the OS/400 program and the Licensed Internal Code. These methods or combinations of methods are used by the DB2 for AS/400 query component to access the data. For complex query tasks, you can nd different solutions that satisfy your requirements for retrieval of data from the database. This appendix is not a cookbook that helps to nd the best performing variation for a query. You have to understand enough about the creation of the access plan and the decisions of the optimizer (discussed in The Optimizer on page 325) to nd the solution that suits your needs. For this reason, this section discusses the following topics that are fundamental for data retrieval from the DB2 for OS/400 database: v Access path v Access method

Appendix D. Query Performance: Design Guidelines and Monitoring

301

Access Path
An access path is: v The order in which records in a database le are organized for processing. v The path used to locate data specied in a query. An access path can be indexed, sequential, or a combination of both.

Arrival Sequence Access Path

An arrival sequence access path is the order of records as they are stored in the le. Processing les using the arrival sequence access path is similar to processing sequential or direct les on traditional systems.

Keyed Sequence Access Path

A keyed sequence access path provides access to a database le that is arranged according to the contents of key elds (indexes). The keyed sequence is the order in which records are retrieved. The access path is automatically maintained whenever records are added to or deleted from the le, or whenever the contents of the index elds are changed. The best example of a keyed sequence access path is a logical le (created using the CRTLF command). Fields that are good candidates for creating keyed sequence access paths are: v Those frequently referenced in query record selection predicates (QRYSLT parameter in OPNQRYF command). v Those frequently referenced in grouping or ordering specications (GRPFLD or KEYFLD parameters in OPNQRYF command). v Those used to join les (see Join Optimization on page 328).
| | | | | | | | | | |

Encoded Vector Access Path

An encoded vector access path provides access to a database le by assigning codes to distinct key values and then representing these values in an array. The elements of the array can be 1, 2, or 4 bytes in length, depending on the number of distinct values that must be represented. Because of their compact size and relative simplicity, encoded vector access paths provide for faster scans that can be more easily processed in parallel. You create encoded vector access paths by using the SQL CREATE INDEX statement. For a further description of access paths, refer to the DB2 for AS/400 SQL Reference and DB2 for AS/400 SQL Programming books.

Access Method
The use of access methods is divided between the Licensed Internal Code and the DB2 for AS/400 query component. The Licensed Internal Code does the low-level processing: selection, join functions, and access path creation. These low-level functions actually involve reading and checking the data. Records that meet the selection criteria are passed back to the calling program. (See Figure 23 on page 301 for an illustration.)

302

OS/400 DB2 for AS/400 Database Programming V4R3

The query optimization process chooses the most efficient access method for each query and keeps this information in the access plan. The type of access is dependent on the number of records, the number of page faults 1, and other criteria (refer to The Optimizer on page 325). This section discusses the possible methods the optimizer can use to retrieve data. The general approach is to either do a data scan (dened below), use an existing index, create a temporary index from the data space, create a temporary index from an existing index, or use the query sort routine. Selection can be implemented through: v Data space scan method (Parallel Data Space Scan Method (DB2 SMP feature only) on page 309) (a data space is an internal object that contains the data in a le) v Parallel pre-fetch method (Parallel Pre-fetch Access Method on page 307) v Key selection method (Key Selection Access Method on page 308) v Key positioning method (Key Positioning Access Method on page 312) v Parallel table or index pre-load (Parallel Table or Index Based Pre-load Access Method on page 317) v Index-from-index method (Index-From-Index Access Method on page 317) v Bitmap processing method (Bitmap Processing Method on page 319) The DB2 SMP feature provides the optimizer with additional methods for retrieving data that include parallel processing. Symmetrical multiprocessing (SMP) is a form of parallelism achieved on a single system where multiple processors (CPU and I/O processors) that share memory and disk resource work simultaneously towards achieving a single end result. This parallel processing means the database manager can have more than one (or all) of the system processors working on a single query simultaneously. The performance of a CPU bound query can be signicantly improved with this feature on multiple-processor systems by distributing the processor load across more than one processor on the system.

1. An interrupt that occurs when a program refers to a (512 byte) page that is not in main storage. Appendix D. Query Performance: Design Guidelines and Monitoring

303

 QUERY CPU CPU CPU CPU SHARED MEMORY

Figure 24. Database Symmetric Multiprocessing

The following methods are available to the optimizer once the DB2 SMP feature has been installed on your system: v Parallel data space scan method (309) v Parallel key selection method (310) v Parallel key positioning method (314) v Parallel index only access method (316) v Parallel hashing method (318) v Parallel bitmap processing method (Bitmap Processing Method on page 319)

Ordering
A KEYFLD parameter must be specied to guarantee a particular ordering of the results. Before parallel access methods were available, the database manager processed le records (and keyed sequences) in a sequential manner that caused the sequencing of the results to be somewhat predictable even though an ordering was not included in the original query request. Because parallel methods cause blocks of le records and key values to be processed concurrently, the ordering of the retrieved results becomes more random and unpredictable. A KEYFLD parameter is the only way to guarantee the specic sequencing of the results. However, an ordering request should only be specied when absolutely required, because the sorting of the results can increase both CPU utilization and response time.

Enabling Parallel Processing

The application or user must enable parallel processing for queries; the optimizer does not automatically use parallelism as the chosen access method. You can use the system-value QQRYDEGREE and the DEGREE parameter on the Change Query Attributes (CHGQRYA) command to control the degree of parallelism that

304

OS/400 DB2 for AS/400 Database Programming V4R3

the query optimizer uses. See Controlling Parallel Processing on page 346 for information on how to control parallel processing. A set of database system tasks are created at system startup for use by the database manager. The tasks are used by the database manager to process and retrieve data from different disk devices. Since these tasks can be run on multiple processors simultaneously, the elapsed time of a query can be reduced. Even though much of the I/O and CPU processing of a parallel query is done by the tasks, the accounting of the I/O and CPU resources used are transferred to the application job. The summarized I/O and CPU resources for this type of application continue to be accurately displayed by the Work with Active Jobs (WRKACTJOB) command.

Automatic Data Spreading

DB2 for AS/400 automatically spreads the data across the disk devices available in the auxiliary storage pool (ASP) where the data is allocated. This ensures that the data is spread without user intervention. The spreading allows the database manager to easily process the blocks of records on different disk devices in parallel. Even though DB2 for AS/400 spreads data across disk devices within an ASP, sometimes the allocation of the data extents (contiguous sets of data) might not be spread evenly. This occurs when there is uneven allocation of space on the devices, or when a new device is added to the ASP. The allocation of the data space may be spread again by saving, deleting, and then restoring the le. Denition of terms used in the following section: v The internal object that contains the data in a le is referred to as a data space. v The rst key elds of an index over multiple elds are referred to as the left-most keys.

Data Space Scan Access Method

The records in the le are processed in no guaranteed order. They will be in arrival sequence. If you want the result in a particular sequence, you must specify the KEYFLD parameter in the OPNQRYF command. Because indexes are not used in arrival sequence order, all records in the le are read. This operation is referred to as a data space scan. The selection criteria is applied to each record, and only the records that match the criteria are returned to the calling application. The data space scan can be very efficient for the following reasons: v It minimizes the number of page I/O operations because all records in a given page are processed, and once the page has been retrieved, it will not be retrieved again. v The database manager can easily predict the sequence of pages from the data space for retrieval; therefore, it can schedule asynchronous I/O of the pages into main storage from auxiliary storage (commonly referred to as pre-fetching). The idea is that the page would be available in main storage by the time the database manager needs to examine the data. This selection method is very good when a large percentage of the records are to be selected (greater than approximately 20%). The data space scan can be adversely affected when selecting records from a le containing deleted records. As you may recall, the delete operation only marks
Appendix D. Query Performance: Design Guidelines and Monitoring

305

records as deleted. For the data space scan, the database manager is going to read all of the deleted records, even though none will be selected. You should use the Reorganize Physical File Member (RGZPFM) CL command to eliminate deleted records. The data space scan is not very efficient when a small percentage of records in the le will be selected. Because all records in the le are examined, this leads to consumption of wasted I/O and processing unit resources. The Licensed Internal Code can use one of two algorithms for selection when a data space scan is processed, intermediate buffer is processed, intermediate buffer selection or data space only selection. The following example illustrates the selection algorithm used by the Licensed Internal Code when selecting records through the intermediate buffer: DO UNTIL END OF FILE 1. Address the next (or rst) record 2. Map all elds to an internal buffer, performing all derived operations. 3. Evaluate the selection criteria to a TRUE or FALSE value using the eld values as they were copied to internal buffer. 4. IF the selection is TRUE THEN Copy the values from the internal buffer into the users answer buffer. ELSE No operation END The following example shows the selection algorithm used by the Licensed Internal Code when selecting records straight from the data space: DO UNTIL END OF FILE 1. Calculate a search limit. This limit is usually the number of records which are already in active memory, or have already had an I/O request done to be loaded into memory. 2. DO UNTIL (search limit reached or record selection criteria is TRUE) a. Address the next (or rst) record b. Evaluate any selection criteria which does not require a derived value directly for the data space record. END 3. IF the selection is true THEN a. Map all elds to an internal buffer, performing all derived operations. b. Copy the values from the internal buffer into the users answer buffer. ELSE No operation END The data-space entry-selection algorithm provides better performance than intermediate buffer selection because of 2 factors: 1. Data movement and computations are only done on records which are selected. 2. The loop in step 2 of the data-space entry-selection algorithm is generated into a executable code burst. When a small percentage of records are actually selected, DB2 for OS/400 will be running this very small program until a record is found.

306

OS/400 DB2 for AS/400 Database Programming V4R3

No action is necessary for queries of this type to make use of the data-space scan method. Any query interface can utilize this improvement. However, the following guidelines determine whether a selection predicate can be implemented as data space only selection: v Neither operand of the predicate can be any kind of a derived value, function, substring, concatenation, or numeric expression. v When both operands of a selection predicate are numeric elds then both elds must have the same type, scale, and precision otherwise one operand is mapped into a derived value. For example, a DECIMAL(3,1) must only be compared against another DECIMAL(3,1) eld. v When one operand of a selection predicate is a numeric eld and the other is a literal or host variable, then the types must be the same and the precision and scale of the literal/host variable must be less than or equal to that of the eld. v Selection predicates involving packed decimal or numeric types of elds can only be done if the table was created by the SQL CREATE TABLE statement. v The varying length character eld cannot be referenced in the selection predicate. v When 1 operand of a selection predicate is a character eld and the other is a literal or host variable, then the length of the host variable can not be greater than that of the eld. v Comparison of character eld data must not require CCSID or key board shift translation. It can be important to avoid intermediate buffer selection because the reduction in CPU and response time for data-space entry selection can be large, in some cases as high as 70-80%. The queries that will benet the most from data space selection are those where less than 60% of the le is actually selected. The lower the percentage of records selected, the more noticeable the performance benet will be.

Parallel Pre-fetch Access Method

DB2 for AS/400 can also use parallel pre-fetch processing to shorten the processing time required for long-running I/O-bound data space scan queries. This method has the same characteristics as data space scan method, except that the I/O processing is done in parallel. This is accomplished by starting multiple input streams for the le to pre-fetch the data. This method is most effective when the following are true: v The data is spread across multiple disk devices. v The query is not CPU-processing-intensive. v There is an ample amount of main storage available to hold the data collected from every input stream. DB2 for AS/400 automatically spreads the data across the disk devices available in the auxiliary storage pool (ASP) where the data is allocated. This ensures that the data is spread without user intervention. Also, at system start, a task is created for each disk device. These tasks process requests to retrieve data from their assigned disk device. Usually the request is for an entire extent (contiguous set of data). This improves performance because the disk device can use smooth sequential access to the data. Because of this optimization, parallel prefetch can pre-load data to active memory faster than the SETOBJACC CL command. Even though DB2 for AS/400 spreads data across disk devices within an ASP, sometimes the allocation of the data space extents may not be spread evenly. This
Appendix D. Query Performance: Design Guidelines and Monitoring

307

occurs when there is uneven allocation of space on the devices or a new device is added to the ASP. The allocation of the data space can be respread by saving, deleting, and restoring the le. The query optimizer selects the candidate queries which can take advantage of this type of implementation. The optimizer selects the candidates by estimating the CPU time required to process the query and comparing the estimate to the amount of time required for input processing. When the estimated input processing time exceeds the CPU time, the query optimizer indicates that the query may be implemented with parallel I/O. The application must enable parallel processing by queries in the job by specifying DEGREE(*ANY) on the Change Query Attribute (CHGQRYA) CL command. Because queries being processed with parallel pre-fetch aggressively utilize main store and disk I/O resources, the number of queries that use parallel pre-fetch should be limited and controlled. Parallel pre-fetch utilizes multiple disk arms, but it does little utilization of multiple CPUs for any given query. Parallel pre-fetch I/O will use I/O resources intensely. Allowing a parallel pre-fetch query on a system with an over committed I/O subsystem may intensify the over-commitment problem. DB2 for AS/400 uses the automated system tuner to determine how much memory this process is allowed to use. At run-time, the Licensed Internal Code will allow parallel pre-fetch to be used only if the memory statistics indicate that it will not over-commit the memory resources. For more information on the paging option see the Automatic System Tuning section of the book Work Management. Parallel pre-fetch requires that enough main storage be available to cache the data being retrieved by the multiple input streams. For large les, the typical extent size is 1 megabyte. This means that 2 megabytes of memory must be available in order to use 2 input streams concurrently. Increasing the amount of available memory in the pool allows more input streams to be used. If there is plenty of available memory, the entire data space for the le may be loaded into active memory when the query is opened.

Key Selection Access Method

This access method requires keyed sequence access paths. The entire index is read and any selection criteria that references the key elds of the index is applied against the index. The advantage of this method is that the data space is only accessed to retrieve records that satisfy the selection criteria applied against the index. Any selection not performed through this key selection method is performed using the data space scan at the data space level. The key selection access method can be very expensive if the search condition applies to a large number of records because: v The whole index is processed. v For every key read from the index, a random I/O to the data space occurs. Normally, the optimizer would choose to use the data space scan when the search condition applies to a large number of records. Only if ordering, grouping, or join operations were specied (these options force the use of an index) would the optimizer choose to use key selection when the search condition selects more than approximately 20% of the keys. In these cases, the optimizer may choose to create a temporary index rather than use an existing index. When the optimizer creates a temporary index it uses a 16K page size. An index created using the CRTLF

308

OS/400 DB2 for AS/400 Database Programming V4R3

command uses only a 4K page size. The optimizer also processes as much selection as possible when building the temporary index. Therefore, nearly all temporary indexes built by the optimizer are select/omit or sparse indexes. The page size difference and corresponding performance improvement from swapping in fewer pages may be enough to overcome the overhead of creating an index. Data space selection is used for building of temporary keyed access paths. If key selection access method is used because the query specied ordering, which forces the use of an index, consider using the following parameters on the OPNQRYF command. This will allow the ordering to be resolved with the query sort routing: v ALWCPYDTA(*OPTIMIZE) and COMMIT(*NO) v ALWCPYDTA(*OPTIMIZE) and COMMIT(*YES) and commitment control is started with a commit level of *NONE, *CHG, or *CS When a query species a select/omit index and the optimizer decides to build a temporary index, all of the selection from the select/omit index is put into the temporary index after any applicable selection from the query.

Parallel Data Space Scan Method (DB2 SMP feature only)

DB2 for AS/400 can use this parallel access method to shorten the processing time required for long-running data space scan queries. The parallel data space scan method reduces the I/O processing time like the parallel pre-fetch access method. In addition, if running on a system that has more than one processor, this method can reduce the elapsed time of a query by splitting the data space scan processing into tasks that can be run on the multiple processors simultaneously. All selection and eld processing is performed in the task. The applications job schedules the work requests to the tasks and merges the results into the result buffer that is returned to the application. This method is most effective when the following are true: v The data is spread across multiple disk devices. v The system has multiple processors that are available. v There is an ample amount of main storage available to hold the data buffers and result buffers. As mentioned earlier, DB2 for AS/400 automatically spreads the data across the disk devices without user intervention, allowing the database manager to pre-fetch le data in parallel. The query optimizer selects the candidate queries that can take advantage of this type of implementation. The optimizer selects the candidates by estimating the CPU time required to process the query and comparing the estimate to the amount of time required for input processing. The optimizer reduces its estimated elapsed time for data space scan based on the number of tasks it calculates should be used. It calculates the number of tasks based on the number of processors in the system, the amount of memory available in the jobs pool, and the current value of the DEGREE query attribute. If the parallel data space scan is the fastest access method, it is then chosen. Parallel data space scan requires that SMP parallel processing be enabled either by the system value QQRYDEGREE or by the DEGREE parameter on the Change Query Attributes (CHGQRYA) command. See Controlling Parallel Processing on page 346 for information on how to control parallel processing.
Appendix D. Query Performance: Design Guidelines and Monitoring

309

Parallel data space scan cannot be used for queries that require any of the following: v Specication of the *ALL commitment control level. v Nested loop join implementation. Page Nested Loop Join Implementation on page 328 v Backward scrolling. For example, parallel data space scan cannot be used for queries dened by the Open Query File (OPNQRYF) command which specify ALWCPYDTA(*YES) or ALWCPYDTA(*NO), because the application might attempt to position to the last record and retrieve previous records. SQL-dened queries that are not dened as scrollable can use this method. Parallel data space scan can be used during the creation of a temporary result, such as a sort or hash operation, no matter what interface was used to dene the query. OPNQRYF can be dened as not scrollable by specifying the *OPTIMIZE parameter value for the ALWCPYDTA parameter, which enables the usage of most of the parallel access methods. v Restoration of the cursor position. For instance, a query requiring that the cursor position be restored as the result of the SQL ROLLBACK HOLD statement or the ROLLBACK CL command. SQL applications using a commitment control level other than *NONE should specify *ALLREAD as the value for precompiler parameter ALWBLK to allow this method to be used. v Update or delete capability. You should run the job in a shared storage pool with the *CALC paging option, as this will cause more efficient use of active memory. For more information on the paging option see the Automatic System Tuning section of the book Work Management. Parallel data space scan requires active memory to buffer the data being retrieved and to separate result buffers for each task. A typical total amount of memory needed for each task is about 2 megabytes. For example, about 8 megabytes of memory must be available in order to use 4 parallel data space scan tasks concurrently. Increasing the amount of available memory in the pool allows more input streams to be used. Queries that access les with large varying length character elds, or queries that generate result values that are larger than the actual record length of the le might require more memory for each task. The performance of parallel data space scan can be severely limited if numerous record locking conicts or data mapping errors occur.

Parallel Key Selection Access Method (available only when the DB2 SMP feature is installed)
For the parallel key selection access method, the possible key values are logically partitioned. Each partition is processed by a separate task just as in the key selection access method. The number of partitions processed concurrently is determined by the query optimizer. Because the keys are not processed in order this method cannot be used by the optimizer if the index is being used for ordering. Key partitions that contain a larger portion of the existing keys from the index are further split as processing of other partitions complete. The following example illustrates a query where the optimizer could choose the key selection method:

310

OS/400 DB2 for AS/400 Database Programming V4R3

 Create an access path INDEX1 keyed over fields LASTNAME and WORKDEPT OPNQRYF FILE((INDEX1)) QRYSLT('WORKDEPT *EQ ''E01''') ALWCPYDTA(*OPTIMIZE)

If the optimizer chooses to run this query in parallel with a degree of four, the following might be the logical key partitions that get processed concurrently:
LASTNAME values leading character partition start 'A' 'G' 'M' 'T' LASTNAME values leading character partition end 'F' 'L' 'S' 'Z'

If there were fewer keys in the rst and second partition, processing of those key values would complete sooner than the third and fourth partitions. After the rst two partitions are nished, the remaining key values in the last two might be further split. The following shows the four partitions that might be processed after the rst and second partition are nished and the splits have occurred:
LASTNAME values leading character partition start 'O' 'Q' 'V' 'X' LASTNAME values leading character partition end 'P' 'S' 'W' 'Z'

Parallel key selection cannot be used for queries that require any of the following: v Specication of the *ALL commitment control level. v Nested loop join implementation. v Backward scrolling. For example, parallel key selection cannot be used for queries dened by the Open Query File (OPNQRYF) command which specify ALWCPYDTA(*YES) or ALWCPYDTA(*NO), because the application might attempt to position to the last record and retrieve previous records. SQL-dened queries that are not dened as scrollable can use this method. Parallel data space scan can be used during the creation of a temporary result, such as a sort or hash operation, no matter what interface was used to dene the query. OPNQRYF can be dened as not scrollable by specifying the *OPTIMIZE parameter value for the ALWCPYDTA parameter, which enables the usage of most of the parallel access methods. v Restoration of the cursor position (for instance, a query requiring that the cursor position be restored as the result of the SQL ROLLBACK HOLD statement or the ROLLBACK CL command). SQL applications using a commitment control level other than *NONE should specify *ALLREAD as the value for precompiler parameter ALWBLK to allow this method to be used. v Update or delete capability. You should run the job in a shared pool with *CALC paging option as this will cause more efficient use of active memory. For more information on the paging option see the Automatic System Tuning section of the Work Management book.

Appendix D. Query Performance: Design Guidelines and Monitoring

311

Parallel key selection requires that SMP parallel processing be enabled either by the system value QQRYDEGREE or by the DEGREE parameter on the Change Query Attributes (CHGQRYA) command. See Controlling Parallel Processing on page 346 for information on how to control parallel processing.

Key Positioning Access Method

This access method is very similar to the key selection access method. They both require a keyed sequence access path. Unlike key selection access method, where processing starts at the beginning of the index and continues to the end, key positioning access method uses selection against the index to position directly to a range of keys that match some, or all, of the selection criteria. It reads all the keys from this range and performs any remaining key selection, similar to the selection performed by the key selection method. Any selection not performed through key positioning or key selection is performed using the data space scan at the data space level. Because key positioning only processes a subset of the keys in the index, it is a better performing method than key selection. The key positioning method is most efficient when a small percentage of records are to be selected (less than approximately 20%). If more than approximately 20% of the records are to be selected, the optimizer generally chooses to: v Use data space scan (index is not required) v Use key selection (if an index is required) v Use query sort routine (if conditions apply) For queries that do not require an index (no ordering, grouping, or join operations), the optimizer attempts to nd an existing index to perform key positioning. If no existing index can be found, the optimizer stops trying to use keyed access to the data because it is faster to use the data space scan than it is to build an index and then perform key positioning. The following example illustrates a query where the optimizer could choose the key positioning method:
Create an access path INDEX1 keyed over field FIELD1 OPNQRYF FILE((INDEX1)) QRYSLT('FIELD1 *EQ ''C''')

In this example, the database support uses Index1 to position to the rst index entry with FIELD1 value equal to C. For each key equal to C, it randomly accesses the data space (random accessing occurs because the keys may not be in the same sequence as the records in the data space) and selects the record. The query ends when the key selection moves beyond the key value of C. Note that for this example all index entries processed and records retrieved meet the selection criteria. If additional selection is added that cannot be performed through key positioning (selection elds do not match the left-most keys of the index), the optimizer uses key selection to perform as much additional selection as possible. Any remaining selection is performed as a data space scan at the data space level.

312

OS/400 DB2 for AS/400 Database Programming V4R3

The key positioning access method has additional processing capabilities. One such capability is to perform range selection across more than one value. For example:
OPNQRYF FILE((ANYFILE)) QRYSLT('FIELD1 *EQ %RANGE(''C'' ''D'')')

In this example, the selection is positioned to the rst index entry equal to value C and then processes records until the last index entry for D is processed. A further extension of this access method, called multirange key positioning, is available. It allows for the selection of records for multiple ranges of values for the left-most key:
OPNQRYF FILE((ANYFILE)) QRYSLT('FIELD1 *EQ %RANGE(''C'' ''D'') *OR 'FIELD1 *EQ %RANGE(''F'' ''H'')')

In this example, the positioning and processing technique is used twice, once for each range of values. Thus far all key positioning examples have used only one key, the left-most key, of the index. Key positioning also handles more than one key (although the keys must be contiguous from the left-most key).
Create an access path INDEX2 keyed over field FIELD1 and FIELD2 OPNQRYF FILE((ANYFILE)) QRYSLT('FIELD1 *EQ ''C'' *OR FIELD2 *EQ ''a''')

In this example without multiple key position support, only the FIELD1=C part of the selection can be applied against the index (single key positioning). While this is fairly good, it means that the result of the index search could still be thousands of records that would have to be searched one by one via key selection on FIELD2. Multiple key positioning support is able to apply both pieces of selection as key positioning, thereby improving performance considerably. Selection is positioned to the index entry whose left-most two keys have values of C and a. This example shows a more interesting use of multiple key positioning.
OPNQRYF FILE((ANYFILE)) QRYSLT('FIELD1 *EQ ''C'' *AND FIELD2 *EQ %VALUES(''a'' ''b'' ''c'' ''d'')')

This query is actually several ranges, and therefore requires more processing to determine that the ranges are:
Appendix D. Query Performance: Design Guidelines and Monitoring

313

between between between between

'Ca' 'Cb' 'Cc' 'Cd'

and and and and

'Ca' 'Cb' 'Cc' 'Cd'

Key positioning is performed over each range, signicantly reducing the number of keys selected. All of the selection can be accomplished through key positioning. This example also contains several ranges:
OPNQRYF FILE((ANYFILE)) QRYSLT('(FIELD1 *EQ ''C'' *AND FIELD2 *EQ %VALUES(''a'' ''b'' ''c'' ''d'')) *OR (FIELD1 *EQ ''D'' *AND FIELD2 *EQ %VALUES(''e'' ''f'')) *OR (FIELD2 *EQ %RANGE(''g'' ''h'') *AND (FIELD1 *EQ ''D'' *OR FIELD1 *EQ ''E'' *OR FIELD1 *EQ ''F''))') between between between between between between between between between 'Ca' 'Cb' 'Cc' 'Cd' 'De' 'Df' 'Dg' 'Eg' 'Fg' and and and and and and and and and 'Ca' 'Cb' 'Cc' 'Cd' 'De' 'Df' 'Dh' 'Eh' 'Fh'

Key positioning is performed over each range. Only those records whose key values fall within one of the ranges are returned. All of the selection can be accomplished through key positioning, signicantly improving the performance of this query.

Parallel Key Positioning Access Method (available only when the DB2 SMP feature is installed)
Using the parallel key positioning access method, the existing key ranges are processed by separate tasks concurrently in separate database tasks. In the example for the key positioning method, if the query optimizer chooses a parallel degree of four, the rst four key ranges of the seven are scanned concurrently. As processing of those ranges completes, the next ones on the list of seven are started. As processing for a range completes and there are no more ranges in the list to process, ranges that still have keys left to process are split, just as in the parallel key selection method. The database manager attempts to keep all of the tasks that are being used busy, each processing a separate key range. Whether using the single value, range of values, or multi-range key positioning, the ranges can be further partitioned and processed simultaneously. Because the keys are not processed in order, this method can not be used by the optimizer if the index is being used for ordering. Consider the following example if the SQL statement is run using parallel degree of four.

314

OS/400 DB2 for AS/400 Database Programming V4R3

 Create an access path INDEX2 keyed over field WORKDEPT and FIRSTNME OPNQRYF FILE((INDEX2)) QRYSLT('(WORKDEPT *EQ ''D11'' *AND FIRSTNME *EQ ''DAVID'') *OR (WORKDEPT *EQ ''D11'' *AND FIRSTNME *EQ ''BRUCE'') *OR (WORKDEPT *EQ ''D11'' *AND FIRSTNME *EQ ''WILL '') *OR (WORKDEPT *EQ ''E11'' *AND FIRSTNME *EQ ''PHIL '') *OR (WORKDEPT *EQ ''E11'' *AND FIRSTNME *EQ ''MAUDE'') *OR (WORKDEPT *EQ ''A00'' *AND FIRSTNME *EQ %RANGE(''CHRISTINE'' ''DELORES'')) *OR (WORKDEPT *EQ ''C01'' *AND FIRSTNME *EQ %RANGE(''CHRISTINE'' ''DELORES''))')

The key ranges the database manager starts with are as follows:
Index INDEX2 Start value 'D11DAVID' 'D11BRUCE' 'D11WILLIAM' 'E11MAUDE' 'E11PHILIP' 'A00CHRISTINE' 'C01CHRISTINE' Index INDEX2 Stop value 'D11DAVID' 'D11BRUCE' 'D11WILLIAM' 'E11MAUDE' 'E11PHILIP' 'A00DELORES' 'C01DELORES'

Range Range Range Range Range Range Range

1 2 3 4 5 6 7

Ranges 1 to 4 are processed concurrently in separate tasks. As soon as one of those four completes, range 5 is started. When another range completes, range 6 is started, and so on. When one of the four ranges in progress completes and there are no more new ones in the list to start, the remaining work left in one of the other key ranges is split and each half is processed separately. Parallel key positioning cannot be used for queries that require any of the following: v Specication of the *ALL commitment control level. v Nested loop join implementation. Page Nested Loop Join Implementation on page 328 v Backward scrolling. For example, parallel key positioning cannot be used for queries dened by the Open Query File (OPNQRYF) command which specify ALWCPYDTA(*YES) or ALWCPYDTA(*NO), because the application might attempt to position to the last record and retrieve previous records. SQL-dened queries that are not dened as scrollable can use this method. Parallel data space scan can be used during the creation of a temporary result, such as a sort or hash operation, no matter what interface was used to dene the query. OPNQRYF can be dened as not scrollable by specifying the *OPTIMIZE parameter value for the ALWCPYDTA parameter, which enables the usage of most of the parallel access methods. v Restoration of the cursor position. For instance, a query requiring that the cursor position be restored as the result of the SQL ROLLBACK HOLD statement or the ROLLBACK CL command. SQL applications using a commitment control level other than *NONE should specify *ALLREAD as the value for precompiler parameter ALWBLK to allow this method to be used. v Update or delete capability.

Appendix D. Query Performance: Design Guidelines and Monitoring

315

You should run the job in a shared pool with the *CALC paging option as this will cause more efficient use of active memory. For more information on the paging option see the Automatic System Tuning section of Work Management book. Parallel key selection requires that SMP parallel processing be enabled either by the system value QQRYDEGREE or by the DEGREE parameter on the Change Query Attributes (CHGQRYA) command. See Controlling Parallel Processing on page 346 for information on how to control parallel processing.

Index Only Access Method

The index only access method can be used in conjunction with any of the key selection or key positioning access methods, including the parallel options for these methods. The processing for the selection does not change from what has already been described for these methods. However, all of the data is extracted from the index rather than performing a random I/O to the data space. The index entry is then used as the input for any derivation or result mapping that might have been specied on the query. The optimizer chooses this method when: v All of the elds that are referenced within the query can be found within a permanent index or within the key elds of a temporary index that the optimizer has decided to create. v The data values must be able to be extracted from the index and returned to the user in a readable format; in other words, none of the key elds that match the query elds have: Absolute value specied Alternate collating sequence or sort sequence specied Zoned or digit force specied v The query does not use a left outer join or an exception join. v For non-SQL users, no variable length or null capable elds require key feedback. The following example illustrates a query where the optimizer could choose to perform index only access.
Create an access path INDEX3 keyed over field WORKDEPT, FIRSTNME, and LASTNAME OPNQRYF FILE((INDEX3)) QRYSLT('(WORKDEPT *EQ ''D11'')' CREATE INDEX X2 ON EMPLOYEE(WORKDEPT,LASTNAME,FIRSTNME) DECLARE BROWSE2 CURSOR FOR SELECT FIRSTNME FROM EMPLOYEE WHERE WORKDEPT = 'D11' OPTIMIZE FOR 99999 ROWS

In this example, the database manager uses INDEX2 to position to the index entries and then extracts the value for the eld FIRSTNME from those entries.

316

OS/400 DB2 for AS/400 Database Programming V4R3

Note that the index key elds do not have to be contiguous to the leftmost key of the index for index only access to be performed. The index is used simply as the source for the data so the database manager can nish processing the query after the selection has been completed. Note: Index only access is implemented on a particular le, so it is possible to perform index only access on some or all of the les of a join query.

Parallel Table or Index Based Pre-load Access Method

Some queries implemented with key selection can require a lot of random I/O in order to access an index or a le. Because of this, a high percentage of the data in the index or le is referenced. DB2 for AS/400 attempts to avoid this random I/O by initiating index- or table-based pre-load when query processing begins. The data is loaded into active memory in parallel as is done for parallel pre-fetch. After the le or index is loaded into memory, random access to the data is achieved without further I/O. The query optimizer recognizes the queries and objects that benet from le or index pre-loads if I/O parallel processing has been enabled. See Controlling Parallel Processing on page 346 for information on how to control parallel processing. The parallel pre-load method can be used with any of the other data access methods. The pre-load is started when the query is opened and control is returned to the application before the pre-load is nished. The application continues fetching records using the other database access methods without any knowledge of pre-load.

Index-From-Index Access Method

The database manager can build a temporary index from an existing index without having to read all of the records in the data space. Generally speaking, this selection method is one of the most efficient. The temporary index that is created only contains keys for records that meet the selection predicates, similar to a select/omit or sparse index. The optimizer chooses this step when: v The query requires an index because it uses grouping, ordering, or join processing. v A permanent index exists that has selection elds as the left-most keys and the left-most keys are very selective. v The selection elds are not the same as the order by, group by, or join-to eld. To process using the index-from-index access method, the database manager rst uses key positioning on the permanent index with the query selection criteria. Secondly, selected record entries are used to build index entries in the new temporary index. The result is an index containing entries in the required key sequence for records that match the selection criteria. A common index-from-index access method example:

Appendix D. Query Performance: Design Guidelines and Monitoring

317

 Create an access path INDEX1 keyed over field FIELD1 OPNQRYF FILE((INDEX1)) QRYSLT('FIELD1 *EQ ''C''') KEYFLD((FIELD2))

For this example, a temporary select/omit access path with primary key FIELD2 is created, containing index entries for those records where FIELD1 = C, assuming FIELD1 = C selects fewer than approximately 20% of the records. Your query may be resolved using the query sort routine if you specify either: v ALWCPYDTA(*OPTIMIZE) and COMMIT(*NO) v ALWCPYDTA(*OPTIMIZE) and COMMIT(*YES) and commitment control is started with a commit level of *NONE, or *CHG, or *CS This decision is based on the number of records to be retrieved.

Hashing Access Method

The hashing access method provides an alternative method for those queries (groupings and joins) that must process data in a grouped or correlated manner. Keyed sequence access paths (indexes) are used to sort and group the data and are effective in some cases for implementing grouping and join query operations. However, if the optimizer had to create a temporary index for that query, extra processor time and resources are used when creating this index before the requested query can be run. The hashing access method can complement keyed sequence access paths or serve as an alternative. For each selected record, the specied grouping or join value in the record is run through a hashing function. The computed hash value is then used to search a specic partition of the hash table. A hash table is similar to a temporary work table, but has a different structure that is logically partitioned based on the specied query. If the records source value is not found in the table, then this marks the rst time that this source value has been encountered in the database table. A new hash table entry is initialized with this rst-time value and additional processing is performed based on the query operation. If the records source value is found in the table, the hash table entry for this value is retrieved and additional query processing is performed based on the requested operation (such as grouping or joining). The hash method can only correlate (or group) identical values; the hash le records are not guaranteed to be sorted in ascending or descending order. The hashing method can be used only when the ALWCPYDTA(*OPTIMIZE) option has been specied unless a temporary result is required, since the hash table built by the database manager is a temporary copy of the selected records. The hashing algorithm allows the database manager to build a hash table that is well-balanced, given that the source data is random and distributed. The hash table itself is partitioned based on the requested query operation and the number of source values being processed. The hashing algorithm then ensures that the new hash table entries are distributed evenly across the hash table partitions. This balanced distribution is necessary to guarantee that scans in different partitions of the hash tables are processing the same number of entries. If one hash table

318

OS/400 DB2 for AS/400 Database Programming V4R3

partition contains a majority of the hash table entries, then scans of that partition are going to have to examine the majority of the entries in the hash table. This is not very efficient. Since the hash method typically processes the records in a table sequentially, the database manager can easily predict the sequence of memory pages from the database table needed for query processing. This is similar to the advantages of the data space scan access method. The predictability allows the database manager to schedule asynchronous I/O of the table pages into main storage (also known as pre-fetching). Pre-fetching enables very efficient I/O operations for the hash method leading to improved query performance. In contrast, query processing with a keyed sequence access method causes a random I/O to the database table for every key value examined. The I/O operations are random since the keyed-order of the data in the index does not match the physical order of the records in the database table. Random I/O can reduce query performance because it leads to unnecessary use of I/O and processor unit resources. A keyed sequence access path can also be used by the hash method to process the le records in keyed order. The keyed access path can signicantly reduce the number of le records that the hash method has to process. This can offset the random I/O costs associated with keyed sequence access paths. The hash table creation and population takes place before the query is opened. Once the hash table has been completely populated with the specied database records, the hash table is used by the database manager to start returning the results of the queries. Additional processing might be required on the resulting hash le records, depending on the requested query operations. Since blocks of le records are automatically spread, the hashing access method can also be performed in parallel so that several groups of records are being hashed at the same time. This shortens the amount of time it takes to hash all the records in the database table. If the DB2 SMP feature is installed, the hashing methods can be performed in parallel.

Bitmap Processing Method

As the name implies, this method generates bitmaps that are used during access to the data space. The bitmap processing method is used for the following reasons: v eliminate the random I/O that occurs on a data space when using an an index (keyed sequence access path) in conjunction with the key position and/or key selection method v allow multiple indexes to be used to access a particular data space In this method, the optimizer chooses one or more indexes (keyed sequence access paths) to be used to aid in selecting records from the data space. Temporary bitmaps are allocated (and initialized), one for each index. Each bitmap contains one bit for each record in the underlying data space. Then, for each index, key positioning and key selection methods are used to apply selection criteria (see prior discussions of the key position method and key selection method). For each index entry selected, the bit associated with that record is set to 1 (that is, turned on). The data space is not accessed during this stage.
Appendix D. Query Performance: Design Guidelines and Monitoring

319

When the processing of the index is complete, the bitmap contains the information on which records are to be selected from the underlying data space. This process is repeated for each index. If two or more indexes are used, the temporary bitmaps are logically ANDed and ORed together to obtain one resulting bitmap. Once the result bitmap is built, it is used to avoid mapping in records from the data space unless they are selected by the query. The indexes used to generate the bitmaps are not actually used to access the resulting selected records. For this reason, they are called tertiary indexes. Conversely, indexes used to access the nal records are called primary indexes. These are the indexes used for ordering, grouping, joins and for selection when no bitmap is used. The bitmap processing method must be used in conjunction with the primary access methods (data space scan, key selection, key positioning, or using a primary index). Like parallel pre-fetch and parallel table or index pre-load, the bitmap processing method does not actually select the records from the data space; instead, it assists the primary methods. If the bitmap is used in conjunction with the data space scan method, it initiates skip-sequential processing. In skip-sequential processing, the data space scan (and parallel data space scan) uses the bitmap to skip over records that are not selected. This has several advantages: v no CPU processing is spent processing those records v input/output is minimized v memory is not ooded with the contents of the entire data space The following example illustrates a query where the query optimizer could choose the bitmap processing method in conjunction with the dataspace scan:
Create an access path IX1 keyed over field WORKDEPT Create an access path IX2 keyed over field SALARY OPNQRYF FILE((EMPLOYEE)) QRYSLT('WORKDEPT=''E01'' *OR SALARY > 50000')

In this example, both indexes IX1 and IX2 are used. The database manager rst generates a bitmap from the results of applying selection WORKDEPT='E01' against index IX1 (using key positioning). It then generates a bitmap from the results of applying selection SALARY > 50000 against index IX2 (again using key positioning). Next, it combines these two bitmaps into one using OR logic. Finally, it initiates a data space scan. The data space scan uses the bitmap to skip through the data space records, retrieving only those selected by the bitmap. This example also shows an additional capability provided with bitmap processing: the use of indexes for ORed selection. This selection precludes the use of just one index (because the OR condition involves different elds). However, using bitmap processing, usage of indexes is possible on selection involving different elds where OR is the major Boolean operator. The query optimizer debug messages put into the job log would look like the following:
CPI4329 Arrival sequence access was used for file EMPLOYEE. CPI4338 2 Access path(s) used for bitmap processing of file EMPLOYEE.

The bitmap can be used in conjunction with a primary index access (where either the key selection or the key positioning method is used on the primary index).

320

OS/400 DB2 for AS/400 Database Programming V4R3

The following example illustrates a query where bitmap processing is used in conjunction with key positioning for a primary index:
Create an access path PIX keyed over field LASTNAME Create an access path TIX1 keyed over field WORKDEPT Create an access path TIX2 keyed over field SALARY OPNQRYF FILE((EMPLOYEE)) KEYFLD(LASTNAME) QRYSLT('WORKDEPT=''E01'' *OR SALARY > 50000')

In this example, indexes TIX1 and TIX2 are used in bitmap processing. The database manager rst generates a bitmap from the results of applying selection WORKDEPT='E01' against index TIX1 (using key positioning). It then generates a bitmap from the results of applying selection SALARY > 50000 against index TIX2 (again using key positioning). Next, it combines these two bitmaps into one using OR logic. Finally, a key selection method is initiated using (primary) index PIX. For each entry in index PIX, the bitmap is checked. For those entries that the bitmap selects, the underlying data space record is selected. The query optimizer debug messages put into the job log would look like the following:
CPI4328 Access path of file PIX was used by query. CPI4338 2 Access path(s) used for bitmap processing of file EMPLOYEE.

Bitmap processing can be used for join queries as well. Since bitmap processing is on a per le basis, each le of a join can independently use or not use bitmap processing. The following example illustrates a query where bitmap processing is used against the second le of a join query but not on the rst le:
Create an access path EPIX keyed over field EMPNO Create an access path TIX1 keyed over field WORKDEPT Create an access path TIX2 keyed over field SALARY OPNQRYF FILE((PROJECT) (EMPLOYEE)) FORMAT(RESULTFILE) JFLD((1/RESPEMP 2/EMPNO)) QRYSLT('2/WORKDEPT=''E01'' *OR 2/SALARY>50000')

In this example, the optimizer decides that the join order is le PROJECT to le EMPLOYEE. Data space scan is used on le PROJECT. For le EMPLOYEE, index EPIX is used to process the join (primary index). Indexes TIX1 and TIX2 are used in bitmap processing. The database manager positions to the rst record in le PROJECT. It then performs the join using index EPIX. Next, it generates a bitmap from the results of applying selection WORKDEPT='E01' against index TIX1 (using key positioning). It then generates a bitmap from the results of applying selection SALARY > 50000 against index TIX2 (again using key positioning). Next, it combines these two bitmaps into one using OR logic. Finally, the entry that EPIX is currently positioned to is checked against the bitmap. The entry is either selected or rejected by the bitmap. If the entry is selected, the records are retrieved from the underlying data space. Next, index EPIX is probed for the next join record. When an entry is found, it is compared against the bitmap and either selected or rejected. Note that the bitmap was generated only once (the rst time it was needed), and is just reused after that. The query optimizer debug messages put into the job log would look like:
CPI4327 CPI4326 CPI4338 File PROJECT processed in join position 1. File EMPLOYEE processed in join position 2. 2 Access path(s) used for bitmap processing of file EMPLOYEE.
Appendix D. Query Performance: Design Guidelines and Monitoring

321

Bitmap processing alleviates some of the headache associated with having composite key indexes (multiple key elds in one index). For example, given a query:
OPNQRYF FILE((EMPLOYEE)) QRYSLT('WORKDEPT=''D11'' *AND FIRSTNME = %VALUES(''DAVID'',''BRUCE'',''WILLIAM''')

An index with keys (WORKDEPT, FIRSTNAME) would be the best index to use to satisfy this query. However, two indexes, one with a key of WORKDEPT and the other with a key of FIRSTNME could be used in bitmap processing, their resulting bitmaps ANDed together, and data space scan used to retrieve the result. A consequence of the bitmap processing method is that it is possible to create several indexes, each with only one key eld, and have the optimizer use them as general purpose indexes for many queries. This alleviates some of the problems involved with trying to come up with the best composite key indexes for all queries being performed against a table. Bitmap processing, in comparison to using a multiple key eld index, allows more ease of use, but at some cost to performance. The best performance is still and will continue to be achieved by using composite key indexes. Some additional points to make on bitmap processing: v Parallel processing can be used whenever bitmap processing is used, as long as the DB2 SMP feature is installed. In this case, the bitmap is built from the results of performing either parallel key positioning and/or parallel key selection on the tertiary index. v Bitmaps are generated at the rst record fetch (I/O). Therefore, it is possible that the rst record fetched will take longer to retrieve than subsequent records. v Bitmaps, by their nature, contain static selection. Once the bitmap is generated, any new or modied records that would now be selected will not be selected by the bitmap. For example, suppose an OPNQRYF statement specifying QRYSLT(QUANTITY > 5) is opened using bitmap processing and the rst record is read. Through a separate database operation, all records where QUANTITY is equal to 4 are updated so QUANTITY is equal to 10. Since the bitmap was already built (during the rst record fetch from the OPNQRYF open identier), these updated records will not be retrieved on subsequent fetches through the OPNQRYF open identier. For this reason, bitmap processing will not be considered by the query optimizer if the ALWCPYDTA option is *NO. The exception to this is if the query contains the GRPFLD clause or one or more aggregate functions (for example, SUM, COUNT, MIN, MAX), in which case static data is already being made. v Bitmap processing cannot be used for a query that is insert, update or delete capable (the OPTION parameter must be set to *INP). Also, the SEQONLY parameter must be set to *YES (and there must not be any overrides to SEQONLY(*NO)).

Data Access Method Summary

The following table provides a summary of the data management methods discussed.

322

OS/400 DB2 for AS/400 Database Programming V4R3

Table 29. Summary of Data Management Methods Access Method Selection Process Good When Data space scan Reads all records. > 20% records selected Selection criteria applied to data in data space. > 20% records Parallel pre-fetch Data retrieved selected from auxiliary storage in parallel 1. Adequate streams. Reads all active memory records. Selection available. criteria applied to 2. Query would data in data otherwise be space. I/O bound. 3. Data spread across multiple disk units. Parallel Data space Scan Data read and selected in parallel tasks.

Not Good When < 20% records selected

< 20% records selected. Query is CPU bound.

Selected When No ordering, grouping, or joining and > 20% records selected. No ordering, grouping, or joining and > 20% records selected.

Advantages Minimizes page I/O through pre-fetching. Minimizes wait time for page I/O through parallel pre-fetching.

> 10% records < 10% records selected, large le selected Query is CPU bound on a 1. Adequate active memory uniprocessor system. available. 2. Data spread across multiple disk units. 3. DB2/400 SMP installed 4. Multi-processor system

1. DB2 SMP installed 2. I/O bound or running on a multiprocessor system

Signicant performance especially on multiproccessors

Key selection

Selection criteria applied to index.

Ordering, grouping, and joining.

Large number of records selected.

Parallel Key selection

Selection criteria applied to index in parallel tasks.

Size of index is much less than the data space. DB2/400 SMP must be installed.

Large number of records selected.

Key positioning

Selection criteria applied to range of index entries. Commonly used option.

< 20% records selected.

> 20% records selected.

Data space accessed only for records matching key selection criteria. When ordering of Better I/O overlap because results not parallel tasks required. perform the I/O. Can fully utilize a multiprocessor systems. Index and data Selection elds space accessed match left-most only for records keys and < 20% matching records selected. selection criteria. Index is required and cannot use key positioning method.

Appendix D. Query Performance: Design Guidelines and Monitoring

323

Table 29. Summary Access Method Parallel Key positioning

of Data Management Methods (continued) Selection Process Good When Not Good When Large number of < 20% records Selection criteria selected. DB2/400 records selected. applied to range of index entries in SMP must be installed. parallel tasks.

Selected When 1. When ordering of results not required.

Advantages

1. Index and data space accessed only for records matching 2. Selection elds selection match criteria. left-most keys 2. Better I/O and < 20% overlap records because selected. parallel tasks perform the I/O.

Index-from-index

Sort routine

Index only

Parallel Table/Index Pre-load

Hashing method Parallel or non-parallel

3. Can fully utilize a multiprocessor systems. > 20% records No existing index Index and data Ordering, Key record selected. to satisfy ordering space accessed grouping and positioning on but existing index only for records permanent index. joining. matching does satisfy Builds temporary selection criteria. selection and index over selecting < 20% selected index records. entries. See data space Ordering < 20% records > 20% records Order data read scan and key selected or small specied; either using data space selected or large no index exists to positioning in this result set of scan processing or result set of le. satisfy the records. records. key positioning. ordering or a large result set is expected. All elds used in Reduced I/O to All elds used in < 20% records Done in combination with the query exist as selected or small the query exist as the data space. key elds and result set of key elds. any of the other DB2/400 SMP is records. DB2/400 SMP index access installed. must be installed methods Index or le data Excessive random Active memory is Excessive random Random page I/O is avoided which activity would already loaded in parallel activity would can improve I/O result from over-committed. to avoid random otherwise occur bound queries. processing the against the object access. query and active and active memory is memory is available which available to hold can hold the the entire object. entire object. Short running Join or grouping Reduce random Longer running records of a specied I/O when group and/or join queries common values compared to queries are group index methods. If together DB2/400 SMP is installed, possible exploitation of SMP parallelism.

324

OS/400 DB2 for AS/400 Database Programming V4R3

Table 29. Summary Access Method Bitmap processing method Parallel or non-parallel

of Data Management Methods (continued) Selection Process Good When Not Good When Indexes probed to < 25% of records > 25% of records selected selected or build resulting memory is bitmap already over-committed

Selected When One or more indexes is found that satises selection and either the query would be I/O bound or the *OR operator is being used

Advantages Allows the use of more than one index per data space. Also reduces random I/O to the data space.

The Optimizer
The optimizer is an important module of the DB2 for AS/400 query component because it makes the key decisions for good database performance. Its main objective is to nd the most efficient access method to the data. This section discusses how the optimizer works in general. The exact algorithms are too complex to be described in detail here and are subject to change from release to release. Query optimization is a trade-off between the time spent to select a query implementation and the time spent to process it. Query optimization must have: v A quick interactive response v An efficient use of total machine resources In deciding how to access data, the optimizer: v Determines possible uses v Picks the optimal method for the DB2 for AS/400 query component to process

Cost Estimation
At run time, the optimizer chooses an optimal access method for the query by calculating an implementation cost given the current state of the database. The optimizer models the access cost of each of the following: v Reading records directly from the le (data space scan) v Reading records through an access path (using either key selection or key positioning) v Creating an access path directly from the data space v Creating an access path from an existing access path (index-from-index) v Using the query sort routine or hashing method (if conditions are satised) The cost of a particular method is the sum of: v The start-up cost v The cost associated with the given optimize parameter (*FIRSTIO, *ALLIO or *MINWAIT) *FIRSTIO Minimize the time required to retrieve the rst buffer of records from the le. Biases the optimization toward not creating an index. Either a data scan or an existing index is preferred.

Appendix D. Query Performance: Design Guidelines and Monitoring

325

When *FIRSTIO is selected, users may also pass in the number of records they expect to retrieve from the query. The optimizer uses this value to determine the percentage of records that will be returned and optimizes accordingly. A small value would minimize the time required to retrieve the rst n records, similar to *FIRSTIO. A large value would minimize the time to retrieve all n records, similar to *ALLIO. *ALLIO Minimize the time to process the whole query assuming that all query records are read from the le. Does not bias the optimizer to any particular access method. Note: If you specify ALWCPYDTA(*OPTIMIZE) and use the sort routine, your query resolves according to the *ALLIO optimize parameter. *MINWAIT Minimize delays when reading records from the le. Minimize I/O time at the expense of open time. Biases optimization toward either creating a temporary index or performing a sort. Either an index is created or an existing index used. v The cost of any access path creations v The expected number of page faults to read the records v The expected number of records to process Page faults and number of records processed may be predicted by: v Statistics the optimizer can obtain from the database objects, including: File size Record size Index size Key size Page faults can also be greatly affected if index only access can be performed, thus eliminating any random I/O to the data space. v A weighted measure of the expected number of records to process is based on what the relational operators in the record selection predicates (called default lter factors) are likely to retrieve: 10% for equal 33% for less-than, greater-than, less-than-equal-to, or greater-than-equal-to 90% for not equal 25% for %RANGE 10% for each %VALUES value Key range estimate is a tool that gives the optimizer a way of gaining much more accurate estimates of the number of expected records selected from one or more selection predicates. The tool determines this by applying the selection predicates against the left-most keys of an existing index. The default lter factors may then be further rened by the estimate based on the key range. If an index exists whose left-most keys match elds used in record selection predicates, it can be used to estimate the number of keys in that index matching the selection criteria. The estimate of the number of keys is based on the number of pages and key density of the machine index without actually accessing the keys. Full indexes over elds used in selection predicates can signicantly help optimization.

326

OS/400 DB2 for AS/400 Database Programming V4R3

Page faults and the number of records processed are dependent on the type of access the optimizer chooses. Refer to Data Management Methods on page 301 for more information on access methods.

Access Plan and Validation

For any query, whenever optimization occurs, an optimized plan of how to access the requested data is developed. The information is kept in what is called a miniplan. The miniplan, along with the query denition template (QDT) that is used to interface with the optimizer, make up an access plan. For OPNQRYF, an access plan is created but is not saved. A new access plan is created each time the OPNQRYF command is processed. For Query/400, an access plan is saved as part of the query denition object. For the SQL program, the access plan is saved as part (in the associated space) of the program containing embedded SQL statements.

Optimizer Decision-Making Rules

In performing its function, the optimizer uses a general set of guidelines to choose the best method for accessing data. The optimizer: v Determines the default lter factor for each predicate in the selection specication. v Extracts attributes of the le from internally stored information. v Performs an estimate key range to determine the true lter factor of the predicates when the selection predicates match the left-most keys of an index. v Determines the cost of creating an index over a le if an index is required. v Determines the cost of using a sort routine or hashing method if selection conditions apply and an index is required. v Determines the cost of data space scan processing if an index is not required. v For each index available, the optimizer does the following until its time limit is exceeded: Extracts attributes of the index from internally stored statistics. Determines if the index meets the selection criteria. Determines the cost of using the index using the estimated page faults and the predicate lter factors to help determine the cost. Compares the cost of using this index with the previous cost (current best). Picks the cheaper one. Continues to search for best index until time out or no more indexes. The time limit factor controls how much time is spent choosing an implementation. It is based on how much time was spent so far and the current best implementation cost found. For small les, the optimizer spends little time in query optimization. For large les, the query optimizer considers more of the indexes. Generally, the optimizer considers ve or six indexes (for each le of a join) before running out of optimization time. If you specify OPTALLAP(*YES) in OPNQRYF, the optimizer does not time out and considers all indexes during its optimization phase. Static SQL programs also do not time out.

Appendix D. Query Performance: Design Guidelines and Monitoring

327

Join Optimization
Join operation is a complex function that requires special attention in order to achieve good performance. A join operation is a complex function that requires special attention in order to achieve good performance. This section describes how DB2 for AS/400 implements join queries and how optimization choices are made by the query optimizer. It also describes design tips and techniques which help avoid or solve performance problems. The optimization for the other types of joins, JDFTVAL(*YES) or JDFTVAL(*ONLYDFT), is similar except that the join order is always the same as specied in the FILE parameter. Information about these types of joins will not be detailed here, but most of the information and tips in this section also apply to joins of this type.

Nested Loop Join Implementation

The DB2 for AS/400 database provides a nested loop join method. For this method, the processing of the les in the join are ordered. This order is called the join order. The rst le in the nal join order is called the primary le. The other les are called secondary les. Each join le position is called a dial. During the join, DB2 for AS/400: 1. Accesses the rst primary le record selected by the predicates local to the primary le. 2. Builds a key value from the join elds in the primary le. 3. Uses key positioning to locate the rst record that satises the join condition for the rst secondary le using a keyed access path with keys matching the join condition or local record selection elds of the secondary le. 4. Determines if the record is selected by applying any remaining selection local to the rst secondary dial. If the secondary dial record is not selected then the next record that satises the join condition is located. Steps 1 5. Returns the result join record. 6. Processes the last secondary le again to nd the next record that satises the join condition in that dial. During this processing, when no more records that satisfy the join condition can be selected, the processing backs up to the logical previous dial and attempts to read the next record that satises its join condition. 7. Ends processing when all selected records from the primary le are processed. Note the following characteristics of a nested loop join: v If result record order (KEYFLD), or group (GRPFLD) processing of the join results is specied over a single le, then that le will become the primary le and will be processed with a keyed access path over the le. v If ordering or grouping of result records is specied on les from other than the primary dial or on elds from two or more dials then the DB2 for AS/400 database will break the processing of the query into two parts. This allows the optimizer to consider any le of the join query as a candidate for the primary le. 1. Process the join query omitting the KEYFLD or GRPFLD processing and write the result records to a temporary work le. Any le of the join query can be considered as a candidate for the primary le.

328

OS/400 DB2 for AS/400 Database Programming V4R3

2. The ordering or grouping processing is then performed on the data in the temporary work le. The OS/400 query optimizer may also decide to break the query into two steps to improve performance when KEYFLD and ALWCPYDTA(*OPTIMIZE) are specied. v All records that satisfy the join condition from each secondary dial are located using a keyed access path. Therefore the records are retrieved from secondary les in random sequence. This random disk I/O time often accounts for a large percentage of the processing time of the query. Since a given secondary dial will be searched once for each record selected from the primary and the preceding secondary dials that satisfy the join condition for each of the preceding secondary dials, a large number of searches may be performed against the later dials. Any inefficiencies in the processing in the selection processing of the later dials can signicantly inate the query processing time. This is the reason why attention to performance considerations for join queries can reduce the run time of a join query from hours to minutes. v Again, all selected records from secondary dials are accessed through a keyed access path. If an efficient keyed access path cannot be found, a temporary keyed access path is created. Some join queries will build temporary access paths over secondary dials even when an access path exists with all of the join keys. Because efficiency is very important for secondary dials of longer running queries, the query optimizer may choose to build a temporary keyed access path which contains only keys which pass the local record selection for that dial. This preprocessing of record selection allows the database manager to process record selection in one pass instead of each time records are matched for a dial.

Hash Join
The hash join method is similar to nested loop join. Instead of using keyed access paths to locate the matching records in a secondary le, however, a hash temporary result le is created that contains all of the records selected by local selection against the le. The structure of the hash table is such that records with the same join value are loaded into the same hash table partition (clustered). The location of the records for any given join value can be found by applying a hashing function to the join value. Hash join has several advantages over nested loop join: v The structure of a hash temporary result table is simpler than that of an index, so less CPU processing is required to build and probe a hash table. v The records in the hash result table contain all of the data required by the query so there is no need to access the data space of the le with random I/O when probing the hash table. v Like join values are clustered, so all matching records for a given join value can usually be accessed with a single I/O request. v The hash temporary result table can be built using SMP parallelism. v Unlike indexes, entries in hash tables are not updated to reect changes of eld values in the underlying le. The existence of a hash table does not affect the processing cost of other updating jobs in the system. Hash join cannot be used for queries that: v Perform some forms of subqueries. v Perform a UNION or UNION ALL. v Perform left outer or exception join.
Appendix D. Query Performance: Design Guidelines and Monitoring

329

v Use a DDS created join logical le. v Require live access to the data as specied by the *NO or *YES parameter values for the ALWCPYDTA precompiler parameter. Hash join is used only for queries running with ALWCPYDTA(*OPTIMIZE). This parameter can be specied either on precompiler commands, the STRSQL CL command, or the OPNQRYF CL command. The Client Access ODBC driver and Query Management driver always uses this mode. Hash join can be used with OPTIMIZE(*YES) if a temporary result is required anyway. v Require that the cursor position be restored as the result of the SQL ROLLBACK HOLD statement or the ROLLBACK CL command. For SQL applications using commitment control level other than *NONE, this requires that *ALLREAD be specied as the value for the ALWBLK precompiler parameter. The query attribute DEGREE, which can be changed by using the Change Query attribute CL command (CHGQRYA), does not enable or disable the optimizer from choosing to use hash join. However, hash join queries can use SMP parallelism if the query attribute DEGREE is set to either *OPTIMIZE, *MAX, or *NBRTASKS. Hash join is used in many of the same cases where a temporary index would have been built. Join queries which are most likely to be implemented using hash join are those where either: v all records in the various les of the join are involved in producing result records v signicant non-join selection is specied against the les of the join which reduces the number of record in the les which are involved with the join result.

Join Optimization Algorithm

The query optimizer must determine the join elds, join operators, local record selection, keyed access path usage, and dial ordering for a join query. The join elds and join operators depend on the join eld specications (JFLD) of the query, the join order, the interaction of join elds with other record selection (QRYSLT), and the keyed access path used. Join specications which are not implemented for the dial are either deferred until they can be processed in a later dial or processed as record selection. For a given dial, the only join specications which are usable as join elds for this dial are those being joined to a previous dial. For example: for the second dial the only join specications that can be used to match records are join specications which reference elds in the primary dial. Likewise, the third dial can only use join specications which reference elds in the primary and the second dials and so on.... Join specications which reference later dials are deferred until that dial is processed or if an inner join was being performed for this dial processed as record selection. For any given dial, only one type of join operator is normally implemented. For example, if one inner join join specication has a join operator of *EQ and the other has a join operator of *GT, the optimizer attempts to implement the join with the *EQ operator. The *GT join specication is processed as record selection after a matching record for the *EQ specication is found. In addition, multiple join specications that use the same operator are implemented together. Note: Only one type of join operator is allowed for either a partial left outer or an exception join.

330

OS/400 DB2 for AS/400 Database Programming V4R3

When looking for an existing keyed access path to access a secondary dial, the query optimizer looks at the left-most key elds of the access path. For a given dial and keyed access path, the join specications which use the left-most key elds can be used. For example:
OPNQRYF FILE((FILE1) (FILE2)) FORMAT(FILE1) JFLD((FILE1/FLDX FILE2/FLDA) (FILE1/FLDZ FILE2/FLDC))

For the keyed access path over FILE2 with key elds FLDA, FLDB, and FLDC, the join operation will be performed only on eld FLDA. After the join is processed, record selection will be done using eld FLDC. The query optimizer will also use local record selection when choosing the best use of the keyed access path for the secondary dial. If the previous example had been expressed with a local predicate as: then the keyed access path with key elds FLDA, FLDB, and FLDC are fully
OPNQRYF FILE((FILE1) (FILE2)) FORMAT(FILE1) QRYSLT('FILE2/FLDB *EQ ''Smith''') JFLD((FILE1/FLDX FILE2/FLDA) (FILE1/FLDZ FILE2/FLDC))

utilized by combining join and selection into one operation against all three key elds. When creating a temporary keyed access path, the left-most key elds are the usable join elds in that dial position. All local record selection for that dial is processed when selecting keys for inclusion into the temporary keyed access path. A temporary keyed access path is similar to the access path created for a select/omit keyed logical le. Since the OS/400 query optimizer attempts a combination of join and local record selection when determining access path usage, it is possible to achieve almost all of the same advantages of a temporary keyed access path by use of an existing access path. In the example above involving FLDA, FLDB, and FLDC, a temporary access path would have been built with the local record selection on FLDB applied during the access paths creation; the temporary access path would have key elds of FLDA and FLDC (to match the join selection). If, instead, an existing keyed access path was used with key elds of FLDA, FLDB, FLDC (or FLDB, FLDA, FLDC or FLDC, FLDB, FLDA or...) the local record selection could be applied at the same time as the join selection (rather than prior to the join selection, as happens when the temporary access path is created). Note the use of the existing keyed access path in this case may have just slightly slower I/O processing than the temporary access path (because the local selection is run many times rather than once) but results in improved query performance by avoiding the temporary access path build altogether.

Join Order Optimization

The join order is xed if any join logical les are referenced, if JORDER(*FILE) is specied, or if JDFTVAL(*YES) or JDFTVAL(*ONLYDFT) is specied. Otherwise, the following join ordering algorithm is used to determine the order of the les:
Appendix D. Query Performance: Design Guidelines and Monitoring

331

1. Determine an access method for each individual le as candidates for the primary dial. 2. Estimate the number of records returned for each le based on local record selection. If the join query with record ordering or group by processing is being processed in one step, then the le with the ordering or grouping elds will be the primary le. 3. Determine an access method, cost, and expected number of records returned for each join combination of candidate les as primary and rst secondary les. The join order combinations estimated for a four le join would be:
1-2 2-1 1-3 3-1 1-4 4-1 2-3 3-2 2-4 4-2 3-4 4-3

4. Choose the combination with the lowest join cost. If the cost is nearly the same then choose the combination which selects the fewest records. 5. Determine the cost, access method, and expected number of records for each remaining le joined to the rst secondary le. 6. Choose the secondary le with the lowest join cost. If the cost is nearly the same then choose the combination which selects the fewest records. 7. Repeat steps 4 through 6 until the lowest cost join order is determined. When JORDER(*FILE) is specied, JDFTVAL(*YES) or JDFTVAL(*ONLYDFT) is specied, or a join logical le is referenced, the OS/400 query optimizer will loop through all of the dials in the order specied and determine the lowest cost access methods.

Costing and Access Path Selection for Join Secondary dials

In step 3 and in step 1, the query optimizer has to estimate a cost and choose an access method for a given dial combination. The choices made are similar to those for record selection except that a keyed access path must be used. As the query optimizer compares the various possible access choices, it must assign a numeric cost value to each candidate and use that value to determine the implementation which will consume the least amount of processing time. This costing value is a combination of CPU and I/O time and is based on the following assumptions: v File pages and keyed access path pages will have to be retrieved from auxiliary storage. For example, the query optimizer is not aware that an entire le may have been loaded into active memory as the result of a SETOBJACC CL command. Usage of this command may signicantly improve the performance of a query, but the optimizer does not change the query implementation to take advantage of the memory resident state of the le. v The query is the only process running on the system. No allowance is given for system CPU utilization or I/O waits which occur because of other processes using the same resources. CPU related costs will be scaled to the relative processing speed of the system running the query. v The values in a eld are uniformly distributed across the le. For example: if 10% of the records in a le have a given value, then it is assumed that every tenth record in the le will contain that value. v The values in a eld are independent from the values in any other elds in a record. For example: If a eld named A has a value of 1 in 50% of the records in

332

OS/400 DB2 for AS/400 Database Programming V4R3

a le and a eld named B has a value of 2 in 50% of the records, then it is expected that a query which selects records where A = 1, and B = 2 selects 25% of the records in the le. The main factors of the join cost calculations for secondary dials are the number of records selected in all previous dials and the number of records which will match, on average, each of the records selected from previous dials. Both of these factors can be derived by estimating the number of matching records for a given dial. When the join operator is something other than equal (*EQ) the expected number of matching records is based on default lter factors: v 33% for less-than, greater-than, less-than-equal-to, or greater-than-equal-to v 90% for not equal v 25% for BETWEEN range v 10% for each IN list value For example, when the join operator is less-than, the expected number of matching records is .33 * (number of records in the dial). If no join specications are active for the current dial, the cartesian product is assumed to be the operator. For cartesian products, the number of matching records is every record in the dial, unless local record selection can be applied to the keyed access path. When the join operator is equal, *EQ, the expected number of records is the average number of duplicate records for a given value. The AS/400 system which performs index maintenance (insertion and deletion of key values in an index) will maintain a running count of the number of unique values for the given key elds in the index. These statistics are bound with the index object and are always maintained. The query optimizer uses these statistics when it is optimizing a query. Maintaining these statistics adds no measurable amount of overhead to index maintenance. This statistical information is only available for indexes which: v Do not contain varying length character keys. Note: If you have varying length character elds used as join elds, you can create an index which maps the varying length character eld to a xed character key using CRTLF CL command. An index that contains xed length character keys dened over varying length data supplies average number of duplicate values statistics. v Were created or rebuilt on an AS/400 system on which Version 2 Release 3 or a later version is installed. Note: The query optimizer can use indexes created on earlier versions of OS/400 to estimate if the join key values have a high or low average number of duplicate values. If the index is dened with only the join keys, the estimate is done based on the size of the index. In many cases, additional keys in the index cause matching record estimates through that index to not be valid. The performance of some join queries may be improved by rebuilding these access paths. Average number of duplicate values statistics are maintained only for the rst 4 left-most keys of the index. For queries which specify more than 4 join elds, it might be benecial to create multiple additional indexes so that an index can be found with average number of duplicate values statistics available within the 4
Appendix D. Query Performance: Design Guidelines and Monitoring

333

left-most key elds. This is particularly important if some of the join elds are somewhat unique (low average number of duplicate values).
Three Field Key Key 1 Key 2 Key 3 Number of unique keys for Key 1 Number of unique keys for Key1 and Key 2 combination Number of unique keys for Key 1, Key2, and Key 3 combination (the full key)

Figure 25. Average Number of Duplicate Values of a Three Key Index

These statistics are maintained as part of index rebuild and creation. Using the average number of duplicate values for equal joins or the default lter value for the other join operators, we now have the number of matching records. The following formula is used to compute the number of join records from previous dials.
NPREV = Rp * M2 * FF2 * ..... *Mn * FFn .....

NPREV is the number of join records from all previous dials. Rp M2 FF2 Mn FFn is the number of records selected from the primary dial. is the number of matching records for dial 2. is the ltering reduction factor for predicates local to dial 2 that are not already applied via M2 above. is the number of matching records for dial n. is the ltering reduction factor for predicates local to dial n that are not already applied using Mn above. Note: Multiply the pair of matching records(Mn) and ltering reduction lter factor(FFn) for each secondary dial preceding the current dial Now that it has calculated the number of join records from previous dials the optimizer is ready to generate a cost for the access method.

334

OS/400 DB2 for AS/400 Database Programming V4R3

Temporary Keyed Access Path from File: The rst access method choice analyzed by the query optimizer is building a temporary keyed access path or hash temporary result table from the le. The basic formula for costing access of a join secondary dial through a temporary keyed access path built from the le or hash table follows:
JSCOST = CRTDSI + NPREV *((MATCH * FF * KeyAccess) + (MATCH * FF * FCost)) * FirstIO

JSCOST CRTDSI NPREV MATCH KeyAccess FF FCost FirstIO

Join Secondary cost Cost to build the temporary keyed access path or a hash temporary result table The number of join records from all previous dials The number of matching records (usually average duplicates) The cost to access a key in a keyed access path or a hash table The ltering factor for local predicates of this dial (excluding selection performed on earlier dials because of transitive closure) The cost to access a record from the le A reduction ratio to reduce the non-startup cost because of an optimization goal to optimize for the rst buffer retrieval. For more information, see Cost Estimation on page 325.

This secondary dial access method will be used if no usable keyed access path is found or the temporary keyed access path or hash table performs better than any existing keyed access path. This method can be better than using any existing access path because the record selection is completed when the keyed access path or hash table is created if any of the following are true: v The number of matches (MATCH) is high. v The number of join records from all previous dials (NPREV) is high. v There is some ltering reduction (FF < 100%). Temporary Keyed Access Path or Hash Table from Keyed Access Path: The basic cost formula for this access method choice is the same as that of using a temporary keyed access path or hash table built from a le, with one exception. The cost to build the temporary keyed access path, CRTDSI, is calculated to include the selection of the records through an existing keyed access path. This access method is used for join secondary dial access for the same reason. However, the creation from a keyed access path might be less costly. Use an Existing Keyed Access Path: The nal access method is to use an existing keyed access path. The basic formula for costing access of a join secondary dial through an existing keyed access path is:
JSCOST = NPREV *((MATCH * KeyAccess) + (MATCH * FCost)) * FirstIO

JSCOST NPREV MATCH KeyAccess

Join Secondary cost The number of join records from all previous dials The number of matching keys which will be found in this keyed access path (usually average duplicates) The cost to access a key in a keyed access path
Appendix D. Query Performance: Design Guidelines and Monitoring

335

FCost FirstIO

The cost to access a record from the le A reduction ratio to reduce the non-startup cost because of an optimization goal to optimize for the rst buffer retrieval. For more information, see Cost Estimation on page 325.

If OPTIMIZE(*FIRSTIO) is used, this is a likely access method because the entire cost is reduced. Also, if the number of join records from all previous dials (NPREV) and the number of matching keys (MATCH) is low this may be the most efficient method. The query optimizer considers using an index which only has a subset of the join elds as the left-most leading keys when: v It is able to determine from the average number of duplicate values statistics that the average number of records with duplicate values is quite low. v The number of records being selected from the previous dials is small. Predicates Generated Through Transitive Closure: For join queries, the query optimizer may do some special processing to generate additional selection. When the set of predicates that belong to a query logically infer extra predicates, the query optimizer generates additional predicates. The purpose is to provide more information during join optimization. Example of Predicates being Added Because of Transitive Closure:
OPNQRYF FILE((T1) (T2)) FORMAT(*LIBL/T1) QRYSLT('T1COL1 = 'A') JFLD((1/T1COL1 2/T2COL1 *EQ))

The optimizer modies the query to be:

OPNQRYF FILE((T1) (T2)) FORMAT(*LIBL/T1) QRYSLT('T1COL1 *EQ 'A' *AND T2COL1 *EQ 'A' ') JFLD((1/T1COL1 2/T2COL1 *EQ))

The following rules determine which predicates are added to other join dials: v The dials affected must have JFLD operators of *EQ. v The predicate is isolatable, which means that a false condition from this predicate would omit the record. v One operand of the predicate is an equal join eld and the other is a literal or host variable. v The predicate operator is not %WLDCRD, %VALUES, or *CT. v The predicate is not connected to other predicates by *OR. v The join type for the dial is an inner join. The query optimizer generates a new predicate, whether or not a predicate already exists in the QRYSLT parameter. Some predicates are redundant. This occurs when a previous evaluation of other predicates in the query already determines the result that predicate provides. Redundant predicates can be specied by you or generated by the query optimizer during predicate manipulation. Redundant predicates with predicate operators of *EQ, *GT, *GE, *LT, *LE, or %RANGE are merged into a single predicate to reect the most selective range.

336

OS/400 DB2 for AS/400 Database Programming V4R3

Sources of Join Query Performance Problems

The optimization algorithms described above benet most join queries, but the performance of a few queries may be degraded. This occurs when: v An access path is not available which provides average number of duplicate values statistics for the potential join elds. Note: See the list at page 333 which provides suggestions on how to avoid the restrictions about indexes statistics or create additional indexes over the potential join elds if they do not exist. v The query optimizer uses default lter factors to estimate the number of records being selected when applying local selection to the le because indexes do not exist over the selection elds. Note: Creating indexes over the selection elds will allow the query optimizer to make a more accurate ltering estimate by using key range estimates. v The particular values selected for the join elds result in signicantly greater number of matching records than the average number of duplicate values for all values of the join elds in the le (i.e. the data is not uniformly distributed). Note: Use DDS to build a logical le with a keyed access path with select/omit specications matching the local record selection. This provides the query optimizer with a more accurate estimate of the number of matching records for the keys are selected. v The query optimizer makes the wrong assumption about the number of records which will be retrieved from the answer set. Note: For OPNQRYF, the wrong performance option value for keyword OPTIMIZE may have been specied. Specifying *FIRSTIO will make the use of an existing index more likely. Specifying *ALLIO will make the creation of a temporary index more likely. Note: For SQL programs, specifying the precompile option ALWCPYDTA(*YES) will bias the queries in that program to be more likely to use an existing index. Likewise, specifying ALWCPYDTA(*OPTIMIZE) will bias the queries in that program to be more likely to create a temporary index. The SQL clause OPTIMIZE FOR nn ROWS can also be used to inuence the OS/400 query optimizer. See Join Optimization on page 343 for more detail on this and for other join performance tips.

Grouping Optimization
This section describes how DB2 for AS/400 implements grouping techniques and how optimization choices are made by the query optimizer. Grouping Hash Implementation: This technique uses the base hash access method to perform grouping or summarization of the selected le records. For each selected record, the specied grouping value is run through the hash function. The computed hash value and grouping value are used to quickly nd the entry in the hash table corresponding to the grouping value. If the current grouping value already has a record in the hash table, the hash table entry is retrieved and summarized (updated) with the current le record values based on the requested grouping eld operations (such as SUM or COUNT). If a hash table entry is not
Appendix D. Query Performance: Design Guidelines and Monitoring

337

found for the current grouping value, a new entry is inserted into the hash table and initialized with the current grouping value. The time required to receive the rst group result for this implementation will most likely be longer than other grouping implementations because the hash table must be built and populated rst. Once the hash table is completely populated, the database manager uses the table to start returning the grouping results. Before returning any results, the database manager must apply any specied grouping selection criteria or ordering to the summary entries in the hash table. The grouping hash method is most effective when the consolidation ratio is high. The consolidation ratio is the ratio of the selected le records to the computed grouping results. If every database le record has its own unique grouping value, then the hash table will become too large. This in turn will slow down the hashing access method. The optimizer estimates the consolidation ratio by rst determining the number of unique values in the specied grouping elds (that is, the expected number of groups in the database le). The optimizer then examines the total number of records in the le and the specied selection criteria and uses the result of this examination to estimate the consolidation ratio. Indexes over the grouping elds can help make the optimizers ratio estimate more accurate. Indexes improve the accuracy because they contain statistics that include the average number of duplicate values for the key elds. See page 333 for more information on index statistics. The optimizer also uses the expected number of groups estimate to compute the number of partitions in the hash table. As mentioned earlier, the hashing access method is more effective when the hash table is well-balanced. The number of hash table partitions directly affects how entries are distributed across the hash table and the uniformity of this distribution. The hash function performs better when the grouping values consist of elds that have non-numeric data types, with the exception of the integer (binary) data type. In addition, specifying grouping value elds that are not associated with the variable length and null eld attributes allows the hash function to perform more effectively. Grouping with Keyed Sequence Implementation: This implementation utilizes the key selection or key positioning access methods to perform the grouping. An index is required that contains all of the grouping elds as contiguous leftmost key elds. The database manager accesses the individual groups through the keyed access path and performs the requested summary functions. Since the index, by denition, already has all of the key values grouped together, the rst group result can be returned in less time than the hashing method. This is because of the temporary result that is required for the hashing method. This implementation can be benecial if an application does not need to retrieve all of the group results or if an index already exists that matches the grouping elds. When the grouping is implemented with an index and a permanent index does not already exist that satises grouping elds, a temporary index is created. The grouping elds specied within the query are used as the key elds for this index.

338

OS/400 DB2 for AS/400 Database Programming V4R3

Optimizer Messages
The OS/400 query optimizer provides you with information messages on the current query processing when the job is under debug mode. These messages appear for OPNQRYF, DB2 for OS/400 Query Manager, interactive SQL, embedded SQL, and in any AS/400 HLL. Every message shows up in the job log; you only need to put your job into debug mode. You will nd that the help on certain messages sometimes offers hints for improved performance. The fastest way to look at the optimizer messages during run time of a program is: v Press the System Request Key. v Press the Enter key. v From the System Request menu, select Option 3 (Display current job). v From the Display Job menu, select Option 10 (Display job log, if active or on job queue). v On the Display Job Log display, press F10 (Display detailed messages). v Now page back and locate the optimizer messages. The display you get after the described procedure may look like this:
Display All Messages Job . . : DSP010004 User . . : QPGMR Number . . . : 5 > opnqryf file((user1/templ)) qryslt('workdept *eq 'E11' *and educlvl *GT 17') All access paths were considered for file TEMPL. Arrival sequence was used for file TEMPL. Press Enter to continue. F3=Exit F5=Refresh F12=Cancel F17=Top F18=Bottom 002103

If you need more information about what the optimizer did, for example: v Why was arrival sequence used v v v v v Why was an index used Why was a temporary index created What keys were used to create the temporary index What order the les were joined in What indexes did the join les use

analyze the messages by pressing the Help key on the message for which you want more information about what happened. If you positioned the cursor on the rst message on the previous example display, you may get a display like this:

Appendix D. Query Performance: Design Guidelines and Monitoring

339

Additional Message Information Message ID . Message type Date sent . . From program To program . . . . . . . . . . . . . . . . . . . . . . . . . . : : : : : CPI432C INFO 07/08/91 QQQIMPLE QQQIMPLE Severity . . . . . . : Time sent . . . . . : Instruction . . . . : Instruction . . . . : 00 09:11:09 0000 0000

Message . . . . : All access paths were considered for file TEMPL. Cause . . . . . : The OS/400 query optimizer considered all access paths built over member TEMPL of file TEMPL in library USER1. The list below shows the access paths considered. If file TEMPL in library USER1 is a logical file then the access paths specified are actually built over member TEMPL of physical file TEMPL in library USER1. Following each access path name in the list is a reason code which explains why the access path was not used. A reason code of 0 indicates that the access path was used to implement the query. USER1/TEMPLIX1 4, USER1/TEMPLIX2 5, USER1/TEMPLIX3 4. The reason codes and their meanings follow: 1 - Access path was not in a valid state. The system invalidated the access path. Press Enter to continue. More... F3=Exit F12=Cancel

You can evaluate the performance of your OPNQRYF command using the informational messages put in the job log by the database manager. The database manager may send any of the following messages when appropriate. The ampersand variables (&1, &X) are replacement variables that contain either an object name or another substitution value when the message appears in the job log. CPI4321 Access path built for le &1. CPI4322 Access path built from keyed le &1. CPI4323 The query access plan has been rebuilt. CPI4324 Temporary le built for le &1. CPI4325 Temporary result le built for query. CPI4326 File &1 processed in join position &X. CPI4327 File &1 processed in join position 1. CPI4328 Access path &4 was used by query. CPI4329 Arrival sequence access was used for le &1. CPI432A Query optimizer timed out. CPI432B Subselects processed as join query. CPI432C All access paths were considered for le &1.

340

OS/400 DB2 for AS/400 Database Programming V4R3

CPI432D Additional access path reason codes were used. CPI432E Selection elds mapped to different attributes. CPI432F Access path suggestion for le &1. CPI4330 &6 tasks used for parallel &10 scan of le &1. CPI4332 &1 host variables used in query. CPI4333 Hashing algorithm used to process join. CPI4334 Query implemented as reusable ODP. CPI4335 Optimizer debug messages for hash join step &1 follow: CPI4337 Temporary hash table built for hash join step &1. CPI4338 &1 access path(s) used for bitmap processing of le &2. CPI4341 Performing distributed query. CPI4342 Performing distributed join for query. CPI4343 Optimizer debug messages for distributed query step &1 of &2 follow: CPI4345 Temporary distributed result le &4 built for query. The above messages refer not only to OPNQRYF, but also to the SQL or Query/400 programs. For a more detailed description of the messages and possible user actions, see DB2 for AS/400 SQL Programming. Additional tools you may want to use when performance tuning queries include the CL commands PRTSQLINF (print SQL information, which applies to SQL programs only) and CHGQRYA (change query attributes). A detailed description of these commands can be found in CL Reference (Abridged).

Miscellaneous Tips and Techniques

The following is a list of the most important query performance tips: 1. Build the indexes that can be used by queries: v Build the indexes to be consistent with the ordering and selection criteria. Use the optimizer messages to help determine the keys needed for consistency. (For more information see Optimizer Messages on page 339.) v Avoid putting commonly updated elds in the index.
Appendix D. Query Performance: Design Guidelines and Monitoring

341

v Avoid unnecessary indexes. The optimizer may time out before reaching a good candidate index. (For more information see Avoiding Too Many Indexes.) 2. Specify ordering criteria on the left-most keys of the index to encourage index use when arrival sequence is selected. 3. When ordering over a eld, try using ALWCPYDTA(*OPTIMIZE). (For more information see ORDER BY and ALWCPYDTA.) 4. For %WLDCRD predicate optimization, avoid using the wildcard in the rst position. (For more information see Index Usage with the %WLDCRD Function on page 343.) 5. For join optimizations: v Avoid joining two les without a JFLD or QRYSLT clause. v Create an index on each secondary le to match join elds. v Make sure the elds used for joining les match in eld length and data type. v Allow the primary le to be the le with the fewest number of selected records (for example, no order by or group by on a large le). v When you specify an ordering on more than 1 le with OPNQRYF, try using ALWCPYDTA(*OPTIMIZE). (For more information about join see Join Optimization on page 343.) 6. Avoid numeric conversion. (For more information see Avoid Numeric Conversion on page 345.) 7. Avoid arithmetic expressions in the selection predicates. (For more information see Avoid Arithmetic Expressions on page 345.) 8. If arrival sequence is used often for queries, use RGZPFM or REUSEDLT(*YES) to remove deleted records. 9. Use QRYSLT rather than GRPSLT if possible.

Avoiding Too Many Indexes

The available indexes for a query are examined in LIFO (last in, rst out) order of creation. If many indexes are available, the optimizer may time out before considering all the indexes. If you are running in debug mode, you will nd in the job log the informational message, CPI432A: Query optimizer timed out for le. If a timeout occurs, you may delete and re-create an index to make it the rst index considered or use the OPTALLAP option in OPNQRYF. This option prevents the optimizer from timing out so that all the indexes are considered.

ORDER BY and ALWCPYDTA

For most queries that include ordering criteria, the optimizer requires the use of an index. If an index is required and no existing index meets the ordering criteria, DB2 for OS/400 database support creates a temporary index for this operation. In some cases, it may be more efficient to sort the records rather than to create a temporary index. Sort is considered for read-only cursors when the following values are specied: v ALWCPYDTA(*OPTIMIZE) and COMMIT(*NO)

342

OS/400 DB2 for AS/400 Database Programming V4R3

v ALWCPYDTA(*OPTIMIZE) and COMMIT(*YES) and commitment control is started with a commit level of *NONE, *CHG or *CS If you specify ALWCPYDTA(*OPTIMIZE) and have a commit level less than *ALL when running the following query,
OPNQRYF FILE((TEMPL)) QRYSLT('DEPT *EQ 'B01') KEYFLD((NAME))

the database manager may: 1. Use an index (on DEPT) or a data scan to resolve the selection criteria. 2. Select the records which meet the selection criteria. 3. Sort the selected records by the values in NAME. ALWCPYDTA(*OPTIMIZE) optimizes the total time required to process the query. However, the time required to receive the rst record may be increased because a copy of the data must be made prior to returning the rst record of the result le. It is very important that an index exist to satisfy the selection criteria. This helps the optimizer to obtain a better estimate of the number of records to be retrieved and to consequently decide whether to use the sort routine or to create a temporary index. Because the sort reads all the query results, the optimizer normally does not perform a sort if OPTIMIZE(*FIRSTIO) is specied. Queries that involve a join operation may take advantage of ALWCPYDTA(*OPTIMIZE). For example, the following join could run faster than the same query with ALWCPYDTA(*YES) specied:
OPNQRYF FILE((FILE1) (FILE2)) FORMAT(FILE12) QRYSLT('FILE1/FLDB *EQ 99 *AND FILE2/FLDY *GE 10') JFLD((FILE1/FLDA FILE2/FLDX)) KEYFLD((FLDA) (FLDY))

Index Usage with the %WLDCRD Function

An index will not be used when the string in the %WLDCRD function starts with a wildcard character of % or _. If the string does not start with a wildcard character (for example, AA%), the optimizer treats the bytes up to the rst wildcard character of the string as a separate selection predicate (for example, A) and optimizes accordingly, possibly choosing to use an index.

Join Optimization
So what do you do if you are looking at a join query which is performing poorly or you are about to create a new application which uses join queries? The following checklist may be useful. 1. Check the database design. Make sure that there are indexes available over all of the join elds and/or record selection elds. If using CRTLF, make sure that the index is not shared. The OS/400 query optimizer will have a better opportunity to select an efficient access method because it can determine the average number of duplicate values. Many queries may be able to use the existing index to implement the query and avoid the cost of creating a temporary index.

Appendix D. Query Performance: Design Guidelines and Monitoring

343

2. Check the query to see whether some complex predicates should be added to other dials thus allowing the optimizer to get a better idea of the selectivity for each dial. Since the query optimizer will not add predicates for predicates connected by *OR, or non-isolable predicates, or predicate operators of %WLDCRD, *CT, or %VALUES. modifying the query by adding these predicates may help. 3. Create a keyed access path which includes Select/Omit specications which match that of the query. This step would help if the statistical characteristics are not uniform for the entire le. For example, if there is one value which has a high duplication factor while the rest of the eld values are unique, then a select/omit keyed access path will allow the optimizer to see that the distribution of values for that key is skewed and make the right optimization given the values being selected. 4. Specify OPTIMIZE(*FIRSTIO) or OPTIMIZE(*ALLIO) If the query is creating a temporary keyed access path and you feel that the processing time would be better if it would only use the existing access path, then specify OPTIMIZE(*FIRSTIO). If the query is not creating a temporary keyed access path and you feel that the processing time would be better if a temporary keyed access path was created then specify OPTIMIZE(*ALLIO). 5. Specify JORDER(*FILE) or create and use a join logical le May help if the OS/400 query optimizer is not selecting the most efficient join order. The risk of taking this action is that this query may not be able to use future DB2 for OS/400 database performance enhancements which depend on being able to switch the join order. 6. Specify ALWCPYDTA(*OPTIMIZE) to allow the OS/400 query optimizer to use a sort routine In the cases where KEYFLD is specied and all of the key elds are from a single dial, this option will allow the OS/400 query optimizer to consider all possible join orders. 7. Specify join predicates to prevent all of the records from one le from being joined to every record in the other le:
OPNQRYF FILE((FILE1) (FILE2) (FILE3)) FORMAT(FILE123) JFLD((FILE1/FLDA FILE2/FLDA) (FILE2/FLDA FILE3/FLDA))

In this example, two join predicates are specied. Each secondary le should have at least one join predicate that references one of its elds as a join-to eld. In the above example, the secondary les, FILE2 and FILE3, both have join predicates that reference FLDA as a join-to eld. 8. A join in which one le is joined with all secondary les consecutively is sometimes called a star join. In the case of a star join where all secondary join tests contain a eld reference to a particular le, there may be performance advantages if that le is placed in join position one. In example A, all les are joined to FILE3. The Query Optimizer can freely determine the join order. The query should be changed to force FILE3 into join position one with the JORDER(*FILE) parameter as shown in example B. Note that in these examples the join type is a join with no default values join (this is, an inner join).

344

OS/400 DB2 for AS/400 Database Programming V4R3

The reason for forcing the le into the rst position is to avoid random I/O processing. If FILE3 is not in join position one, every record in FILE3 could be examined repeatedly during the join process. If FILE3 is fairly large, considerable random I/O processing occurs resulting in poor performance. By forcing FILE3 to the rst position random I/O processing is minimized. Example A: Star Join Query
OPNQRYF FILE((FILE1) (FILE2) (FILE3) (FILE4) + FORMAT(RFORMAT) + JFLD((FILE3/JFLD1 FILE1/JFLD1) + (FILE3/JFLD1 FILE2/JFLD1) + (FILE3/JFLD1 FILE4/JFLD1))

Example B: Star Join Query with JORDER(*FILE) Parameter

OPNQRYF FILE((FILE3) (FILE2) (FILE4) (FILE1) + FORMAT(RFORMAT) + JFLD((FILE3/JFLD1 FILE1/JFLD1) + (FILE3/JFLD1 FILE2/JFLD1) + (FILE3/JFLD1 FILE4/JFLD1)) JORDER(*FILE)

Note: Specifying elds from FILE3 only on the KEYFLD parameter may also have the effect of placing FILE3 in join position 1. This allows the Query Optimizer to choose the best order for the remaining les.

Avoid Numeric Conversion

If the le your query is accessing contains numeric elds, you should avoid numeric conversions. As a general guideline, you should always use the same data type for elds and literals used in a comparison. If the data type of the literal has greater precision than the data type of the eld, the optimizer will not use an index created on that eld. To avoid problems for elds and literals being compared, use the: v Same data type v Same scale, if applicable v Same precision, if applicable In the following example, the data type for the EDUCLVL eld is INTEGER. If an index was created on that eld, then the optimizer does not use this index in the rst OPNQRYF. This is because the precision of the literal is greater than the precision of the eld. In the second OPNQRYF, the optimizer considers using the index, because the precisions are equal. Example where EDUCLVL is INTEGER:
Instead of: OPNQRYF FILE((TEMPL)) QRYSLT('EDUCLVL *GT 17.0') Specify: OPNQRYF FILE((TEMPL)) QRYSLT('EDUCLVL *GT 17') Index"NOT"used Index"used

Avoid Arithmetic Expressions

You should never have an arithmetic expression as an operand to be compared to a eld in a record selection predicate. The optimizer does not use an index on a eld that is being compared to an arithmetic expression.

Appendix D. Query Performance: Design Guidelines and Monitoring

345

Instead of: OPNQRYF FILE((TEMPL)) Specify: OPNQRYF FILE((TEMPL))

QRYSLT('SALARY *GT 15000*1.1') QRYSLT('SALARY *GT 16500')

Index"NOT"used Index"used

Controlling Parallel Processing

This section describes how parallel processing can be turned on and off. If DB2 Symmetric Multiprocessing feature is installed then symmetric multiprocessing (SMP) can also be turned on and off. This control is available for system wide control through the system value QQRYDEGREE. At a job level, this control is available using the DEGREE parameter on the CHGQRYA command. Even though parallelism has been enabled for a system or given job, the individual queries that run in a job might not actually use a parallel method. This might be because of functional restrictions, or the optimizer might choose a non-parallel method because it runs faster. See the previous sections that describe the performance characteristics and restrictions of each of the parallel access methods. Because queries being processed with parallel access methods aggressively use main storage, CPU, and disk resources, the number of queries that use parallel processing should be limited and controlled.

Controlling Parallel Processing System Wide

The QQRYDEGREE system value can be used to control parallel processing for a system. The current value of the system value can be displayed or modied using the following CL commands: v WRKSYSVAL - Work with System Value v CHGSYSVAL - Change System Value v DSPSYSVAL - Display System Value v RTVSYSVAL - Retrieve System Value The special values for QQRYDEGREE control whether parallel processing is allowed by default for all jobs on the system. The possible values are: *NONE No parallel processing is allowed for database query processing. *IO I/O parallel processing is allowed for queries. *OPTIMIZE The query optimizer can choose to use any number of tasks for either I/O or SMP parallel processing to process the queries. SMP parallel processing is used only if the DB2 SMP feature is installed. The query optimizer chooses to use parallel processing to minimize elapsed time based on the jobs share of the memory in the pool. *MAX The query optimizer can choose to use either I/O or SMP parallel processing to process the query. SMP parallel processing can be used only if the DB2 SMP feature is installed. The choices made by the query optimizer are similar to those made for parameter value *OPTIMIZE, except the optimizer assumes that all active memory in the pool can be used to process the query.

346

OS/400 DB2 for AS/400 Database Programming V4R3

The default value of the QQRYDEGREE system value is *NONE, so the value must be changed if parallel query processing is desired as the default for jobs run on the system. Changing this system value affects all jobs that will be run or are currently running on the system whose DEGREE query attribute is *SYSVAL. However, queries that have already been started or queries using reusable ODPs are not affected.

Controlling Parallel Processing for a Job

Query parallel processing can also be controlled at the job level using the DEGREE parameter of the Change Query Attributes (CHGQRYA) command. The parallel processing option allowed and, optionally, the number of tasks that can be used when running database queries in the job can be specied. You can prompt on the CHGQRYA command in an interactive job to display the current values of the DEGREE query attribute. Changing the DEGREE query attribute does not affect queries that have already been started or queries using reusable ODPs. The parameter values for the DEGREE keyword are: *SAME The parallel degree query attribute does not change. *NONE No parallel processing is allowed for database query processing. *IO Any number of tasks can be used when the database query optimizer chooses to use I/O parallel processing for queries. SMP parallel processing is not allowed. *OPTIMIZE The query optimizer can choose to use any number of tasks for either I/O or SMP parallel processing to process the query. SMP parallel processing can be used only if the DB2 SMP feature is installed. Use of parallel processing and the number of tasks used is determined with respect to the number of processors available in the system, the jobs share of the amount of active memory available in the pool in which the job is run, and whether the expected elapsed time for the query is limited by CPU processing or I/O resources. The query optimizer chooses an implementation that minimizes elapsed time based on the jobs share of the memory in the pool. *MAX The query optimizer can choose to use either I/O or SMP parallel processing to process the query. SMP parallel processing can be used only if the DB2 SMP feature is installed. The choices made by the query optimizer are similar to those made for parameter value *OPTIMIZE except the optimizer assumes that all active memory in the pool can be used to process the query. *NBRTASKS number-of-tasks Species the number of tasks to be used when the query optimizer chooses to use SMP parallel processing to process a query. I/O parallelism is also allowed. SMP parallel processing cam be used only if the DB2 SMP feature is installed. Using a number of tasks less than the number of processors available on the system restricts the number of processors used simultaneously for running a given query. A larger number of tasks ensures that the query is allowed to use
Appendix D. Query Performance: Design Guidelines and Monitoring

347

all of the processors available on the system to run the query. Too many tasks can degrade performance because of the over commitment of active memory and the overhead cost of managing all of the tasks. *SYSVAL Species that the processing option used should be set to the current value of the QQRYDEGREE system value. *ANY Parameter value *ANY has the same meaning as *IO. The *ANY value is maintained for compatibility with prior releases. The initial value of the DEGREE attribute for a job is *SYSVAL. See the CL Reference (Abridged) book for more information about the CHGQRYA command.

Monitoring Database Query Performance

You can gather performance statistics for a specic query or for every query on the system. There are two means of gathering the statistics: v The Start Database Monitor (STRDBMON) and End Database Monitor (ENDDBMON) commands. v The Start Performance Monitor (STRPFRMON) command with the STRDBMON parameter. With the performance statistics gathered you can generate various reports. Some possibilities are reports that show queries that: v Use an abundance of the system resources. v Take an extremely long time to execute. v Did not run because of the query governor time limit. v Create a temporary keyed access path during execution v Use the query sort during execution v Could perform faster with the creation of a keyed logical le containing keys suggested by the query optimizer. Note: A query that is cancelled by an end request generally does not generate performance statistics.

Start Database Monitor (STRDBMON) Command

The STRDBMON command starts the collection of database performance statistics for a specic job or all jobs on the system. The statistics are placed in an output database le and member specied on the command. If the output le and/or member does not exist, one is created based upon the le and format denition of model le QSYS/QAQQDBMN. If the output le and/or member exist, the record format of the output le must be named QQQDBMN. You can specify a replace/append option that allows you to clear the member of information before writing records or to just append new information to the end of the existing le. You can also specify a force record write option that allows you to control how many records are kept in the record buffer of each job being monitored before

348

OS/400 DB2 for AS/400 Database Programming V4R3

forcing the records to be written to the output le. By specifying a force record write value of 1, FRCRCD(1), monitor records will appear in the log as soon as they are created. FRCRCD(1) also ensures that the physical sequence of the records are most likely, but not guaranteed, to be in time sequence. However, FRCRCD(1) will cause the most negative performance impact on the jobs being monitored. By specifying a larger number for the FRCRCD parameter, the performance impact of monitoring can be lessened. Specifying *DETAIL on the TYPE parameter of the STRDBMON command indicates that detail records, as well as summary records, are to be collected. This is only useful for non-SQL queries, those queries which do not generate a QQQ1000 record. For non-SQL queries the only way to determine the number of records returned and the total time to return those records is to collect detail records. Currently the only detail record is QQQ3019. The DDS for this record is shown in Figure 43 on page 395. While the detail record contains valuable information it creates a slight performance degradation for each block of records returned. Therefore its use should be closely monitored. If the monitor is started on all jobs, any jobs waiting on job queues or any jobs started during the monitoring period will have statistics gathered from them once they begin. If the monitor is started on a specic job, that job must be active in the system when the command is issued. Each job in the system can be monitored concurrently by only two monitors: v One started specically on that job. v One started on all jobs in the system. When a job is monitored by two monitors and each monitor is logging to a different output le, monitor records will be written to both logs for this job. If both monitors have selected the same output le then the monitor records are not duplicated in the output le.

End Database Monitor (ENDDBMON) Command

The ENDDBMON command ends the Database Monitor for a specic job or all jobs on the system. If an attempt to end the monitor on all jobs is issued, there must have been a previous STRDBMON issued for all jobs. If a particular job is specied on this command, the job must have the monitor started explicitly and specically on that job. In the following sequence: 1. Start monitoring all jobs in the system. 2. Start monitoring a specic job. 3. End monitoring on all jobs. The specic job monitor continues to run because an explicit start of the monitor was done on it. It continues to run until an ENDDBMON on the specic job is issued. In 1. 2. 3. the following sequence: Start monitoring all jobs in the system. Start monitoring a specic job. End monitoring on the specic job.

The all job monitor continues to run, even over the specic job, until an ENDDBMON for all jobs is issued.
Appendix D. Query Performance: Design Guidelines and Monitoring

349

In 1. 2. 3.

the following sequence: Start monitoring a specic job. Start monitoring all jobs in the system. End monitoring on all jobs.

The specic job monitor continues to run until an ENDDBMON for the specic job is issued. In 1. 2. 3. the following sequence: Start monitoring a specic job. Start monitoring all jobs in the system. End monitoring on the specic job.

The all job monitor continues to run for all jobs, including the specic job. When an all job monitor is ended, all of the jobs on the system will be triggered to close the output le, however, the ENDDBMON command can complete before all of the monitored jobs have written their nal performance records to the log. Use the work with object locks, WRKOBJLCK, CL command to see that all of the monitored jobs no longer hold locks on the output le before assuming the monitoring is complete.

Database Monitor Performance Records

The records in the database le are uniquely identied by their record identication number. These records are dened in several different logical les which are not shipped with the system and must be created by the user, if desired. The logical les can be created with the DDS shown in Database Monitor Logical File DDS on page 362. The eld descriptions are explained in the tables following each gure. Note: The database monitor logical les are keyed logical les that contain some select/omit criteria. Therefore, there will be some maintenance overhead associated with these les while the database monitor is active. The user may wish to minimize this overhead while the database monitor is active, especially if monitoring all jobs. When monitoring all jobs the number of records generated could be quite large. Possible ways to minimize maintenance overhead associated with database monitor logical les: v Do not create the database monitor logical les until the database monitor has completed. v Create the database monitor logical les using dynamic select/omit criteria (DYNSLT keyword on logical les DDS). v Create the database monitor logical les with rebuild access path maintenance specied on the CRTLF command (*REBLD option on MAINT parameter). By minimizing the maintenance overhead at run time, you are merely delaying the maintenance cost until the database monitor logical le is either created or opened. The choice is to either spend the time while the database monitor is active or spend the time after the database monitor has completed.

350

OS/400 DB2 for AS/400 Database Programming V4R3

Query Optimizer Index Advisor

The query optimizer analyzes the record selection in the query and determines, based on default values, if creation of a permanent index would improve performance. If a permanent index would be benecial, it returns the key elds necessary to create the suggested index. The index advisor information can be found in the Database Monitor logical les QQQ3000, QQQ3001 and QQQ3002. The advisor information is stored in elds QQIDXA, QQIDXK and QQIDXD. When the QQIDXA eld contains a value of Y the optimizer is advising you to create an index using the key elds shown in eld QQIDXD. The intention of creating this index is to improve the performance of the query. In the list of key elds contained in eld QQIDXD the optimizer has listed what it considers the suggested primary and secondary key elds. Primary key elds are elds that should signicantly reduce the number of keys selected based on the corresponding query selection. Secondary key elds are elds that may or may not signicantly reduce the number of keys selected. The optimizer is able to perform key positioning over any combination of the primary key elds, plus one additional secondary key eld. Therefore it is important that the rst secondary key eld be the most selective secondary key eld. The optimizer will use key selection with any of the remaining secondary key elds. While key selection is not as fast as key positioning it can still reduce the number of keys selected. Hence, secondary key elds that are fairly selective should be included. Field QQIDXK contains the number of suggested primary key elds that are listed in eld QQIDXD. These are the left-most suggested key elds. The remaining key elds are considered secondary key elds and are listed in order of expected selectivity based on the query. For example, assuming QQIDXK contains the value of 4 and QQIDXD species 7 key elds, then the rst 4 key elds specied in QQIDXK would be the primary key elds. The remaining 3 key elds would be the suggested secondary key elds. It is up to the user to determine the true selectivity of any secondary key elds and to determine whether those key elds should be included when creating the index. When building the index the primary key elds should be the left-most key elds followed by any of the secondary key elds the user chooses and they should be prioritized by selectivity. Note: After creating the suggested index and executing the query again, it is possible that the query optimizer will choose not to use the suggested index.

Database Monitor Examples

Suppose you have an application program with SQL statements and you want to analyze and performance tune these queries. The rst step in analyzing the performance is collection of data. The following examples show how you might collect and analyze data using STRDBMON and ENDDBMON. Performance data is collected in LIB/PERFDATA for an application running in your current job. The following sequence collects performance data and prepares to analyze it.
Appendix D. Query Performance: Design Guidelines and Monitoring

351

1. STRDBMON FILE(LIB/PERFDATA). If this le does not already exist, the command will create one from the skeleton le in QSYS/QAQQDBMN. 2. Run your application 3. ENDDBMON 4. Create logical les over LIB/PERFDATA using the DDS shown in Database Monitor Logical File DDS on page 362. You are now ready to analyze the data. The following examples give you a few ideas on how to use this data. You should closely study the physical and logical le DDS to understand all the data being collected so you can create queries that give the best information for your applications.

Performance Analysis Example 1

Determine which queries in your SQL application are implemented with table scans. The complete information can be obtained by joining two logical les: QQQ1000, which contains information about the SQL statements, and QQQ3000, which contains data about queries performing table scans. The following SQL query could be used:
SELECT A.QQTLN, A.QQTFN, A.QQTOTR, A.QQIDXA, B.QQROWR, (B.QQETIM - B.QQSTIM) AS TOT_TIME, B.QQSTTX FROM LIB/QQQ3000 A, LIB/QQQ1000 B WHERE A.QQJFLD = B.QQJFLD AND A.QQUCNT = B.QQUCNT

Sample output of this query is shown in Table 30. The critical thing to understand is the join criteria
WHERE A.QQJFLD = B.QQJFLD AND A.QQUCNT = B.QQUCNT

A lot of data about many queries is contained in multiple records in le LIB/PERFDATA. It is not uncommon for data about a single query to be contained in 10 or more records within the le. The combination of dening the logical les and then joining the les together allows you to piece together all the data for a query or set of queries. Field QQJFLD uniquely identies all data common to a job; eld QQUCNT is unique at the query level. The combination of the two, when referenced in the context of the logical les, connects the query implementation to the query statement information. scale=table-scale-factor
Table 30. Output for SQL Queries that Performed Lib Name Table Total Index Name Rows Advised LIB1 TBL1 20000 Y LIB1 LIB1 TBL2 TBL1 100 20000 N Y Table Scans Rows TOT_TIME Statement Text Returned 10 6.2 SELECT * FROM LIB1/TBL1 WHERE FLD1 = 'A' 100 0.9 SELECT * FROM LIB1/TBL2 32 7.1 SELECT * FROM LIB1/TBL1 WHERE FLD1 = 'B' AND FLD2 > 9000

If the query does not use SQL, the SQL information record (QQQ1000) is not created. This makes it more difficult to determine which records in LIB/PERFDATA pertain to which query. When using SQL, record QQQ1000 contains the actual SQL statement text that matches the performance records to the corresponding query. Only through SQL is the statement text captured. For queries executed using the

352

OS/400 DB2 for AS/400 Database Programming V4R3

OPNQRYF command, the OPNID parameter is captured and can be used to tie the records to the query. The OPNID is contained in eld QQOPID of record QQQ3014.

Performance Analysis Example 2

Similar to the preceding example that showed which SQL applications were implemented with table scans, the following example shows all queries that are implemented with table scans.
SELECT A.QQTLN, A.QQTFN, A.QQTOTR, A.QQIDXA, B.QQOPID, B.QQTTIM, C.QQCLKT, C.QQRCDR, D.QQROWR, (D.QQETIM - D.QQSTIM) AS TOT_TIME, D.QQSTTX FROM LIB/QQQ3000 A INNER JOIN LIB/QQQ3014 B ON (A.QQJFLD = B.QQJFLD AND A.QQUCNT = B.QQUCNT) LEFT OUTER JOIN LIB/QQQ3019 C ON (A.QQJFLD = C.QQJFLD AND A.QQUCNT = C.QQUCNT) LEFT OUTER JOIN LIB/QQQ1000 D ON (A.QQJFLD = D.QQJFLD AND A.QQUCNT = D.QQUCNT)

In this example, the output for all queries that performed table scans are shown in Table 31. Note: The elds selected from le QQQ1000 do return NULL default values if the query was not executed using SQL. For this example assume the default value for character data is blanks and the default value for numeric data is an asterisk (*).
Table 31. Output for All Queries that Performed Table Scans Clock Lib Table Total Index Query ODP Time Name Name Rows Advised OPNID Open Time LIB1 TBL1 20000 Y 1.1 4.7 Recs Rtned 10 Rows Rtned 10 TOT_ TIME 6.2 Statement Text

SELECT * FROM LIB1/TBL1 WHERE FLD1 = 'A' SELECT * FROM LIB1/TBL2 SELECT * FROM LIB1/TBL1 WHERE FLD1 = 'A' AND FLD2 > 9000

LIB1 LIB1

TBL2 TBL1

100 20000

N Y

0.1 2.6

0.7 4.4

100 32

100 32

0.9 7.1

LIB1

TBL4

4000

QRY04

1.2

4.2

724

If the SQL statement text is not needed, joining to le QQQ1000 is not necessary. You can determine the total time and rows selected from data in the QQQ3014 and QQQ3019 records.

Performance Analysis Example 3

Your next step may include further analysis of the table scan data. The previous examples contained a eld titled Index Advised. A Y (yes) in this eld is a hint from the query optimizer that the query may perform better with an index to access the data. For the queries where an index is advised, notice that the records selected by the query are low in comparison to the total number of records in the

Appendix D. Query Performance: Design Guidelines and Monitoring

353

table. This is another indication that a table scan may not be optimal. Finally, a long execution time may highlight queries that may be improved by performance tuning. The next logical step is to look into the index advised optimizer hint. The following query could be used for this:
SELECT A.QQTLN, A.QQTFN, A.QQIDXA, A.QQIDXD, A.QQIDXK, B.QQOPID, C.QQSTTX FROM LIB/QQQ3000 A INNER JOIN LIB/QQQ3014 B ON (A.QQJFLD = B.QQJFLD AND A.QQUCNT = B.QQUCNT) LEFT OUTER JOIN LIB/QQQ1000 C ON (A.QQJFLD = C.QQJFLD AND A.QQUCNT = C.QQUCNT) WHERE A.QQIDXA = 'Y'

There are two slight modications from the rst example. First, the selected elds have been changed. Most important is the selection of eld QQIDXD that contains a list of possible key elds to use when creating the index suggested by the query optimizer. Second, the query selection limits the output to those table scan queries where the optimizer advises that an index be created (A.QQIDXA = Y). Table 32 shows what the results might look like.
Table 32. Output with Recommended Key Fields Lib Name Table Index Advised Name Advised Key Fields LIB1 TBL1 Y FLD1 LIB1 TBL1 Y FLD1, FLD2 FLD1, FLD4 Advised Primary Key 1 1 Query OPNID Statement Text

SELECT * FROM LIB1/TBL1 WHERE FLD1 = 'A' SELECT * FROM LIB1/TBL1 WHERE FLD1 = 'B' AND FLD2 > 9000 QRY04

LIB1

TBL4

At this point you should determine whether it makes sense to create a permanent index as advised by the optimizer. In this example, creating one index over LIB1/TBL1 would satisfy all three queries since each use a primary or left-most key eld of FLD1. By creating one index over LIB1/TBL1 with key elds FLD1, FLD2, there is potential to improve the performance of the second query even more. The frequency these queries are run and the overhead of maintaining an additional index over the le should be considered when deciding whether or not to create the suggested index. If you create a permanent index over FLD1, FLD2 the next sequence of steps would be to: 1. Start the performance monitor again 2. Re-run the application 3. End the performance monitor 4. Re-evaluate the data. It is likely that the three index-advised queries are no longer performing table scans.

354

OS/400 DB2 for AS/400 Database Programming V4R3

Additional Database Monitor Examples

The following are additional ideas or examples on how to extract information from the performance monitor statistics. All of the examples assume data has been collected in LIB/PERFDATA and the documented logical les have been created. 1. How many queries are performing dynamic replans?
SELECT COUNT(*) FROM LIB/QQQ1000 WHERE QQDYNR <> 'NA'

2. What is the statement text and the reason for the dynamic replans?
SELECT QQDYNR, QQSTTX FROM LIB/QQQ1000 WHERE QQDYNR <> 'NA'

Note: You have to refer to the description of eld QQDYNR for denitions of the dynamic replan reason codes. 3. How many indexes have been created over LIB1/TBL1?
SELECT FROM WHERE AND COUNT(*) LIB/QQQ3002 QQTLN = 'LIB1' QQTFN = 'TBL1'

4. What key elds are used for all indexes created over LIB1/TBL1 and what is the associated SQL statement text?
SELECT FROM WHERE AND AND AND A.QQTLN, A.QQTFN, A.QQIDXD, B.QQSTTX LIB/QQQ3002 A, LIB/QQQ1000 B A.QQJFLD = B.QQJFLD A.QQUCNT = B.QQUCNT A.QQTLN = 'LIB1' A.QQTFN = 'TBL1'

Note: This query shows key elds only from queries executed using SQL. 5. What key elds are used for all indexes created over LIB1/TBL1 and what was the associated SQL statement text or query open ID?
SELECT A.QQTLN, A.QQTFN, A.QQIDXD, B.QQOPID,C.QQSTTX FROM LIB/QQQ3002 A INNER JOIN LIB/QQQ3014 B ON (A.QQJFLD = B.QQJFLD AND A.QQUCNT = B.QQUCNT) LEFT OUTER JOIN LIB/QQQ1000 C ON (A.QQJFLD = C.QQJFLD AND A.QQUCNT = C.QQUCNT) WHERE A.QQTLN = 'LIB1' AND A.QQTFN = 'TBL1'

Note: This query shows key elds from all queries on the system. 6. What types of SQL statements are being performed? Which are performed most frequently?
SELECT QQSTOP, COUNT(*) FROM LIB/QQQ1000 GROUP BY QQSTOP ORDER BY 2 DESC

7. Which SQL queries are the most time consuming? Which user is running these queries?
SELECT (QQETIM - QQSTIM), QQUSER, QQSTTX FROM LIB/QQQ1000 ORDER BY 1 DESC

8. Which queries are the most time consuming?

Appendix D. Query Performance: Design Guidelines and Monitoring

355

SELECT (A.QQTTIM + B.QQCLKT), A.QQOPID, C.QQSTTX FROM LIB/QQQ3014 A LEFT OUTER JOIN LIB/QQQ3019 B ON (A.QQJFLD = B.QQJFLD AND A.QQUCNT = B.QQUCNT) LEFT OUTER JOIN LIB/QQQ1000 C ON (A.QQJFLD = C.QQJFLD AND A.QQUCNT = C.QQUCNT) ORDER BY 1 DESC

Note: This example assumes detail data has been collected into record QQQ3019. 9. Show the data for all SQL queries with the data for each SQL query logically grouped together.
SELECT FROM WHERE AND A.* LIB/PERFDATA A, LIB/QQQ1000 B A.QQJFLD = B.QQJFLD A.QQUCNT = B.QQUCNT

Note: This might be used within a report that will format the the interesting data into a more readable format. For example, all reason code elds could be expanded by the report to print the denition of the reason code (i.e., physical eld QQRCOD = T1 means a table scan was performed because no indexes exist over the queried le). 10. How many queries are being implemented with temporary les because a key length of greater than 2000 bytes or more than 120 key elds was specied for ordering?
SELECT COUNT(*) FROM LIB/QQQ3004 WHERE QQRCOD = 'F6'

11. Which SQL queries were implemented with nonreusable ODPs?

SELECT FROM WHERE AND AND B.QQSTTX LIB/QQQ3010 A, LIB/QQQ1000 B A.QQJFLD = B.QQJFLD A.QQUCNT = B.QQUCNT A.QQODPI = 'N'

12. What is the estimated time for all queries stopped by the query governor?
SELECT QQEPT, QQOPID FROM LIB/QQQ3014 WHERE QQGVNS = 'Y'

Note: This example assumes detail data has been collected into record QQQ3019. 13. Which queries estimated time exceeds actual time?
SELECT A.QQEPT, (A.QQTTIM + B.QQCLKT), A.QQOPID, C.QQTTIM, C.QQSTTX FROM LIB/QQQ3014 A LEFT OUTER JOIN LIB/QQQ3019 B ON (A.QQJFLD = B.QQJFLD AND A.QQUCNT = B.QQUCNT) LEFT OUTER JOIN LIB/QQQ1000 C ON (A.QQJFLD = C.QQJFLD AND A.QQUCNT = C.QQUCNT) WHERE A.QQEPT/1000 > (A.QQTTIM + B.QQCLKT)

Note: This example assumes detail data has been collected into record QQQ3019.

356

OS/400 DB2 for AS/400 Database Programming V4R3

14. Should a PTF for queries that perform UNION exists be applied. It should be applied if any queries are performing UNION. Do any of the queries perform this function?
SELECT COUNT(*) FROM QQQ3014 WHERE QQUNIN = 'Y'

Note: If result is greater than 0, the PTF should be applied. 15. You are a system administrator and an upgrade to the next release is planned. A comparison between the two releases would be interesting. v Collect data from your application on the current release and save this data in LIB/CUR_DATA v Move to the next release v Collect data from your application on the new release and save this data in a different le: LIB/NEW_DATA v Write a program to compare the results. You will need to compare the statement text between the records in the two les to correlate the data.

Appendix D. Query Performance: Design Guidelines and Monitoring

357

Database Monitor Physical File DDS

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor physical file record format A* A R QQQDBMN TEXT('Database + Monitor') A QQRID 15P TEXT('Record + ID') + EDTCDE(4) + COLHDG('Record' 'ID') A QQTIME Z TEXT('Time record was + created') + COLHDG('Created' 'Time') A QQJFLD 46H TEXT('Join Field') + COLHDG('Join' 'Field') A QQRDBN 18A TEXT('Relational + Database Name') + COLHDG('Relational' + 'Database' 'Name') A QQSYS 8A TEXT('System Name') + COLHDG('System' 'Name') A QQJOB 10A TEXT('Job Name') + COLHDG('Job' 'Name') A QQUSER 10A TEXT('Job User') + COLHDG('Job' 'User') A QQJNUM 6A TEXT('Job Number') + COLHDG('Job' 'Number') A QQUCNT 15P TEXT('Unique Counter') + ALWNULL + COLHDG('Unique' 'Counter') A QQUDEF 100A VARLEN TEXT('User Defined + Field') + ALWNULL + COLHDG('User' 'Defined' + 'Field') A QQSTN 15P TEXT('Statement Number') + ALWNULL + COLHDG('Statement' + 'Number') A QQQDTN 15P TEXT('Subselect Number') + ALWNULL + COLHDG('Subselect' 'Number') A QQQDTL 15P TEXT('Nested level of + subselect') + ALWNULL + COLHDG('Nested' + 'Level of' + 'Subselect') A QQMATN 15P TEXT('Subselect of + materialized view') + ALWNULL + COLHDG('Subselect of' + 'Materialized' 'View') A QQMATL 15P TEXT('Nested level of + Views subselect') + ALWNULL + COLHDG('Nested Level' + 'of View's' + 'Subselect')

Figure 26. QSYS/QAQQDBMN Performance Statistics Physical File DDS (1 of 4)

358

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A QQTLN 10A TEXT('Library') + ALWNULL + COLHDG('Library' 'Name') A QQTFN 10A TEXT('File') + ALWNULL + COLHDG('File' 'Name') A QQTMN 10A TEXT('Member') + ALWNULL + COLHDG('Member' 'Name') A QQPTLN 10A TEXT('Physical Library') + ALWNULL + COLHDG('Library of' + 'Physical File') A QQPTFN 10A TEXT('Physical File') + ALWNULL + COLHDG('Name of' + 'Physical File') A QQPTMN 10A TEXT('Physical Member') + ALWNULL + COLHDG('Member of' + 'Physical' File') A QQILNM 10A TEXT('Index Library') + ALWNULL + COLHDG('Index' 'Library') A QQIFNM 10A TEXT('Index File') + ALWNULL + COLHDG('Index' 'Name') A QQIMNM 10A TEXT('Index Member') + ALWNULL + COLHDG('Index' 'Member') A QQNTNM 10A TEXT('NLSS Table') + ALWNULL + COLHDG('NLSS' 'Table') A QQNLNM 10A TEXT('NLSS Library') + ALWNULL + COLHDG('NLSS' 'Library') A QQSTIM Z TEXT('Start timestamp') + ALWNULL + COLHDG('Start' 'Time') A QQETIM Z TEXT('End timestamp') + ALWNULL + COLHDG('End' 'Time') A QQKP 1A TEXT('Key positioning') + ALWNULL + COLHDG('Key' 'Positioning') A QQKS 1A TEXT('Key selection') + ALWNULL + COLHDG('Key' 'Selection') A QQTOTR 15P TEXT('Total row in table') + ALWNULL + COLHDG('Total' 'Rows') A QQTMPR 15P TEXT('Number of rows in + temporary') + ALWNULL + COLHDG('Number' 'of Rows' + 'in Temporary') A QQJNP 15P TEXT('Join Position') + ALWNULL + COLHDG('Join' 'Position')

Figure 27. QSYS/QAQQDBMN Performance Statistics Physical File DDS (2 of 4)

Appendix D. Query Performance: Design Guidelines and Monitoring

359

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A QQEPT 15P TEXT('Estimated processing + time') + ALWNULL + COLHDG('Estimated' + 'Processing' 'Time') A QQDSS 1A TEXT('Data space + selection') ALWNULL COLHDG('Data' 'Space' + 'Selection') A QQIDXA 1A TEXT('Index advised') + ALWNULL + COLHDG('Index' 'Advised') A QQORDG 1A TEXT('Ordering') ALWNULL COLHDG('Ordering') A QQGRPG 1A TEXT('Grouping') + ALWNULL + COLHDG('Grouping') A QQJNG 1A TEXT('Join') ALWNULL COLHDG('Join') A QQUNIN 1A TEXT('Union') + ALWNULL + COLHDG('Union') A QQSUBQ 1A TEXT('Subquery') + ALWNULL + COLHDG('Subquery') A QQHSTV 1A TEXT('Host Variables') + ALWNULL + COLHDG('Host' 'Variables') A QQRCDS 1A TEXT('Record Selection') + ALWNULL + COLHDG('Record' 'Selection') A QQRCOD 2A TEXT('Reason Code') + ALWNULL + COLHDG('Reason' 'Code') A QQRSS 15P TEXT('Number of rows + selected or sorted') + ALWNULL + COLHDG('Number' + 'of Rows' 'Selected') A QQREST 15P TEXT('Estimated number + of rows selected') + ALWNULL + COLHDG('Estimated' + 'Number of' + 'Rows Selected') A QQRIDX 15P TEXT('Number of entries + in index created') + ALWNULL + COLHDG('Number of' + 'Entries in' + 'Index Created') A QQFKEY 15P TEXT('Estimated keys for + key positioning') + ALWNULL + COLHDG('Estimated' + 'Entries for' + 'Key Positioning')

Figure 28. QSYS/QAQQDBMN Performance Statistics Physical File DDS (3 of 4)

360

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A QQKSEL 15P TEXT('Estimated keys for + key selection') + ALWNULL + COLHDG('Estimated' + 'Entries for' + 'Key Selection') A QQAJN 15P TEXT('Estimated number + of joined rows') + ALWNULL + COLHDG('Estimated' + 'Number of' + 'Joined Rows') A QQIDXD 1000A VARLEN TEXT('Key fields + for the index advised') + ALWNULL + COLHDG('Advised' 'Key' + 'Fields') A QQC11 1A ALWNULL A QQC12 1A ALWNULL A QQC13 1A ALWNULL A QQC14 1A ALWNULL A QQC15 1A ALWNULL A QQC16 1A ALWNULL A QQC18 1A ALWNULL A QQC21 2A ALWNULL A QQC22 2A ALWNULL A QQC23 2A ALWNULL A QQI1 15P ALWNULL A QQI2 15P ALWNULL A QQI3 15P ALWNULL A QQI4 15P ALWNULL A QQI5 15P ALWNULL A QQI6 15P ALWNULL A QQI7 15P ALWNULL A QQI8 15P ALWNULL A QQI9 15P ALWNULL TEXT('Thread + Identifier') + COLHDG('Thread' + 'Identifier') A QQIA 15P ALWNULL A QQF1 15P ALWNULL A QQF2 15P ALWNULL A QQF3 15P ALWNULL A QQC61 6A ALWNULL A QQC81 8A ALWNULL A QQC82 8A ALWNULL A QQC83 8A ALWNULL A QQC84 8A ALWNULL A QQC101 10A ALWNULL A QQC102 10A ALWNULL A QQC103 10A ALWNULL A QQC104 10A ALWNULL A QQC105 10A ALWNULL A QQC106 10A ALWNULL A QQC181 18A ALWNULL A QQC182 18A ALWNULL A QQC183 18A ALWNULL A QQC301 30A VARLEN ALWNULL A QQC302 30A VARLEN ALWNULL A QQC303 30A VARLEN ALWNULL A QQ1000 1000A VARLEN ALWNULL A QQTIM1 Z ALWNULL A QQTIM2 Z ALWNULL

Figure 29. QSYS/QAQQDBMN Performance Statistics Physical File DDS (4 of 4)

Appendix D. Query Performance: Design Guidelines and Monitoring

361

Database Monitor Logical File DDS

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 1000 A* A R QQQ1000 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQRCNT RENAME(QQI5) + COLHDG('Refresh' + 'Counter') A QQUDEF A QQSTN A QQSTF RENAME(QQC11) + COLHDG('Statement' + 'Function') A QQSTOP RENAME(QQC21) + COLHDG('Statement' + 'Operation') A QQSTTY RENAME(QQC12) + COLHDG('Statement' 'Type') A QQPARS RENAME(QQC13) + COLHDG('Parse' 'Required') A QQPNAM RENAME(QQC103) + COLHDG('Package' 'Name') A QQPLIB RENAME(QQC104) + COLHDG('Package' 'Library') A QQCNAM RENAME(QQC181) + COLHDG('Cursor' 'Name') A QQSNAM RENAME(QQC182) + COLHDG('Statement' 'Name') A QQSTIM A QQSTTX RENAME(QQ1000) + COLHDG('Statement' 'Text') A QQSTOC RENAME(QQC14) + COLHDG('Statement' + 'Outcome') A QQROWR RENAME(QQI2) + COLHDG('Rows' 'Returned') A QQDYNR RENAME(QQC22) + COLHDG('Dynamic' 'Replan') A QQDACV RENAME(QQC16) + COLHDG('Data' 'Conversion') A QQTTIM RENAME(QQI4) + COLHDG('Total' 'Time') A QQROWF RENAME(QQI3) + COLHDG('Rows' 'Fetched') A QQETIM A K QQJFLD A S QQRID CMP(EQ 1000)

Figure 30. Summary record for SQL Information

362

OS/400 DB2 for AS/400 Database Programming V4R3

Table 33. QQQ1000 - Summary record for SQL Information Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQRCNT QQUDEF QQSTN QQSTF Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQRCNT QQUDEF QQSTN QQC11 Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) Unique refresh counter User dened eld Statement number (unique per statement) Statement function S - Select U - Update I - Insert D - Delete L - Data denition language O - Other

Appendix D. Query Performance: Design Guidelines and Monitoring

363

Table 33. QQQ1000 - Summary record for SQL Information (continued) Logical Field Name QQSTOP Physical Field Name QQC21 Description Statement operation AL - Alter table CA - Call CL - Close CO - Comment on CM - Commit CN - Connect CC - Create collection CI - Create index CT - Create table CV - Create view DP - Declare procedure DL - Delete DE - Describe DT - Describe table DI - Disconnect DR - Drop EX - Execute EI - Execute immediate FE - Fetch GR - Grant IN - Insert LO - Label on LK - Lock OP - Open PR - Prepare RE - Release RV - Revoke RO - Rollback SI - Select into SC - Set connection ST - Set transaction UP - Update Statement type D - Dynamic statement S - Static statement Parse required, Y - Yes N - No Name of the package or name of the program that contains the current SQL statement Name of the library containing the package Name of the cursor corresponding to this SQL statement, if applicable Name of statement for SQL statement, if applicable Time this statement entered Statement text Statement outcome S - Successful U - Unsuccessful Number of result rows returned

QQSTTY

QQC12

QQPARS

QQC13

QQPNAM QQPLIB QQCNAM QQSNAM QQSTIM QQSTTX QQSTOC

QQC103 QQC104 QQC181 QQC182 QQSTIM QQ1000 QQC14

QQROWR

QQI2

364

OS/400 DB2 for AS/400 Database Programming V4R3

Table 33. QQQ1000 - Summary record for SQL Information (continued) Logical Field Name QQDYNR Physical Field Name QQC22 Description Dynamic replan (access plan rebuilt) NA - No replan. NR - SQL QDT rebuilt for new release. A1 - A le or member is not the same object as the one referenced when the access plan was last built. Some reasons they could be different are: - Object was deleted and recreated. - Object was saved and restored. - Library list was changed. - Object was renamed. - Object was moved. - Object was overridden to a different object. - This is the rst run of this query after the object containing the query has been restored. A2 - Access plan was built to use a reusable Open Data Path (ODP) and the optimizer chose to use a non-reusable ODP for this call. A3 - Access plan was built to use a non-reusable Open Data Path (ODP) and the optimizer chose to use a reusable ODP for this call. A4 - The number of records in the le member has changed by more than 10% since the access plan was last built. A5 - A new access path exists over one of the les in the query. A6 - An access path that was used for this access plan no longer exists or is no longer valid. A7 - OS/400 Query requires the access plan to be rebuilt because of system programming changes. A8 - The CCSID of the current job is different than the CCSID of the job that last created the access plan. A9 - The value of one or more of the following is different for the current job than it was for the job that last created this access plan: - date format. - date separator. - time format. - time separator. AA - The sort sequence table specied is different than the sort sequence table that was used when this access plan was created. AB - Storage pool changed or DEGREE parameter of CHGQRYA command changed.

Appendix D. Query Performance: Design Guidelines and Monitoring

365

Table 33. QQQ1000 - Summary record for SQL Information (continued) Logical Field Name QQDACV Physical Field Name QQC16 Description Data conversion N - No. 0 - Not applicable. 1 - Lengths do not match. 2 - Numeric types do not match. 3 - C host variable is NUL-terminated 4 - Host variable or column is variable length and the other is not variable length. 5 - CCSID conversion. 6 - DRDA and NULL capable, variable length, contained in a partial row, derived expression, or blocked fetch with not enough host variables. 7 - Data, time, or timestamp column. 8 - Too many host variables. 9 - Target table of an insert is not an SQL table. Total time for this statement, in milliseconds. For fetches, this includes all fetches for this OPEN of the cursor. Total rows fetched for cursor Time SQL request completed

QQTTIM

QQI4

QQROWF QQETIM

QQI3 QQETIM

366

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3000 A* A R QQQ3000 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQTLN A QQTFN A QQTMN A QQPTLN A QQPTFN A QQPTMN A QQTOTR A QQREST A QQAJN A QQEPT A QQJNP A QQJNDS RENAME(QQI1) + COLHDG('Data Space' 'Number') A QQJNMT RENAME(QQC21) + COLHDG('Join' 'Method') A QQJNTY RENAME(QQC22) + COLHDG('Join' 'Type') A QQJNOP RENAME(QQC23) + COLHDG('Join' 'Operator') A QQIDXK RENAME(QQI2) + COLHDG('Advised' 'Primary' 'Keys') A QQDSS A QQIDXA A QQRCOD A QQIDXD A K QQJFLD A S QQRID CMP(EQ 3000)

Figure 31. Summary record for Arrival Sequence

Table 34. QQQ3000 - Summary record for Arrival Sequence Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS Description Record identication Time record was created Join eld (unique per job) Relational database name System name

Appendix D. Query Performance: Design Guidelines and Monitoring

367

Table 34. QQQ3000 - Summary record for Arrival Sequence (continued) Logical Field Name QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQTOTR QQREST QQAJN QQEPT QQJNP QQJNDS QQJNMT Physical Field Name QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQTOTR QQREST QQAJN QQEPT QQJNP QQI1 QQC21 Description Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level Materialized view QDT number Materialized view nested level Library File Member Physical library Physical le Physical member Total rows in table Estimated number of rows selected Estimated number of joined rows Estimated processing time, in seconds Join position - when available Data space number Join method - when available NL - Nested loop MF - Nested loop with selection HJ - Hash join Join type - when available IN - Inner join PO - Left partial outer join EX - Exception join Join operator - when available EQ - Equal NE - Not equal GT - Greater than GE - Greater than or equal LT - Less than LE - Less than or equal CP - Cartesian product Number of advised key elds that use key positioning

QQJNTY

QQC22

QQJNOP

QQC23

QQIDXK

QQI2

368

OS/400 DB2 for AS/400 Database Programming V4R3

Table 34. QQQ3000 - Summary record for Arrival Sequence (continued) Logical Field Name QQDSS Physical Field Name QQDSS Description Data space selection Y - Yes N - No Index advised Y - Yes N - No Reason code T1 - No indexes exist. T2 - Indexes exist, but none could be used. T3 - Optimizer chose table scan over available indexes. Key elds for the index advised

QQIDXA

QQIDXA

QQRCOD

QQRCOD

QQIDXD

QQIDXD

Appendix D. Query Performance: Design Guidelines and Monitoring

369

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3001 A* A R QQQ3001 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQTLN A QQTFN A QQTMN A QQPTLN A QQPTFN A QQPTMN A QQILNM A QQIFNM A QQIMNM A QQTOTR A QQREST A QQFKEY A QQKSEL A QQAJN A QQEPT A QQJNP A QQJNDS RENAME(QQI1) + COLHDG('Data Space' 'Number') A QQJNMT RENAME(QQC21) + COLHDG('Join' 'Method') A QQJNTY RENAME(QQC22) + COLHDG('Join' 'Type') A QQJNOP RENAME(QQC23) + COLHDG('Join' 'Operator') A QQIDXK RENAME(QQI2) + COLHDG('Advised' 'Primary' 'Keys') A QQKP A QQKPN RENAME(QQI3) + COLHDG('Number of Key' + ) 'Positioning' + 'Fields') A QQKS A QQDSS A QQIDXA A QQRCOD A QQIDXD A K QQJFLD A S QQRID CMP(EQ 3001)

Figure 32. Summary record for Using Existing Index

370

OS/400 DB2 for AS/400 Database Programming V4R3

Table 35. QQQ3001 - Summary record for Using Existing Index Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQILNM QQIFNM QQIMNM QQTOTR QQREST QQFKEY QQKSEL QQAJN QQEPT QQJNP QQJNDS QQJNMT Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQILNM QQIFNM QQIMNM QQTOTR QQREST QQFKEY QQKSEL QQAJN QQEPT QQJNP QQI1 QQC21 Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level Materialized view QDT number Materialized view nested level Library File Member Physical library Physical le Physical member Index library Index le Index member Total rows in table Estimated number of rows selected Keys selected thru key positioning Keys selected thru key selection Estimated number of joined rows Estimated processing time, in seconds Join position - when available Data space number Join method - when available NL - Nested loop MF - Nested loop with selection HJ - Hash join

Appendix D. Query Performance: Design Guidelines and Monitoring

371

Table 35. QQQ3001 - Summary record for Using Existing Index (continued) Logical Field Name QQJNTY Physical Field Name QQC22 Description Join type - when available IN - Inner join PO - Left partial outer join EX - Exception join Join operator - when available EQ - Equal NE - Not equal GT - Greater than GE - Greater than or equal LT - Less than LE - Less than or equal CP - Cartesian product Number of advised key elds that use key positioning Key positioning Y - Yes N - No Key selection Y - Yes N - No Data space selection Y - Yes N - No Index advised Y - Yes N - No Reason code I1 - Record selection I2 - Ordering/Grouping I3 - Record selection and Ordering/Grouping I4 - Nested loop join I5 - Record selection using bitmap processing Key elds for index advised

QQJNOP

QQC23

QQIDXK QQKP

QQI2 QQKP

QQKS

QQKS

QQDSS

QQDSS

QQIDXA

QQIDXA

QQRCOD

QQRCOD

QQIDXD

QQIDXD

372

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* Database Monitor logical file 3002 A R QQQ3002 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQTLN A QQTFN A QQTMN A QQPTLN A QQPTFN A QQPTMN A QQILNM A QQIFNM A QQIMNM A QQNTNM A QQNLNM A QQSTIM A QQETIM A QQTOTR A QQRIDX A QQREST A QQFKEY A QQKSEL A QQAJN A QQJNP A QQJNDS RENAME(QQI1) + COLHDG('Data Space' 'Number') A QQJNMT RENAME(QQC21) + COLHDG('Join' 'Method') A QQJNTY RENAME(QQC22) + COLHDG('Join' 'Type') A QQJNOP RENAME(QQC23) + COLHDG('Join' 'Operator') A QQIDXK RENAME(QQI2) + COLHDG('Advised' 'Primary' 'Keys') A QQEPT A QQKP A QQKPN RENAME(QQI3) + COLHDG('Number of Key' + 'Positioning' + 'Fields') A QQKS A QQDSS A QQIDXA A QQRCOD A QQIDXD A QQCRTK RENAME(QQ1000) + COLHDG('Key Fields' + 'of Index' 'Created') A K QQJFLD A S QQRID CMP(EQ 3002)

Figure 33. Summary record for Index Created

Appendix D. Query Performance: Design Guidelines and Monitoring

373

Table 36. QQQ3002 - Summary record for Index Created Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQILNM QQIFNM QQIMNM QQNTNM QQNLNM QQSTIM QQETIM QQTOTR QQRIDX QQREST QQFKEY QQKSEL QQAJN QQEPT QQJNP QQJNDS Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQILNM QQIFNM QQIMNM QQNTNM QQNLNM QQSTIM QQETIM QQTOTR QQRIDX QQREST QQFKEY QQKSEL QQAJN QQEPT QQJNP QQI1 Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level Materialized view QDT number Materialized view nested level Library File Member Physical library Physical le Physical member Index library Index le Index member NLSS library NLSS table Start timestamp End timestamp Total rows in table Number of entries in index created Estimated number of rows selected Keys selected thru key positioning Keys selected thru key selection Estimated number of joined rows Estimated processing time, in seconds Join position - when available Data space number

374

OS/400 DB2 for AS/400 Database Programming V4R3

Table 36. QQQ3002 - Summary record for Index Created (continued) Logical Field Name QQJNMT Physical Field Name QQC21 Description Join method - when available NL - Nested loop MF - Nested loop with selection HJ - Hash join Join type - when available IN - Inner join PO - Left partial outer join EX - Exception join Join operator - when available EQ - Equal NE - Not equal GT - Greater than GE - Greater than or equal LT - Less than LE - Less than or equal CP - Cartesian product Number of advised key elds that use key positioning Key positioning Y - Yes N - No Key selection Y - Yes N - No Data space selection Y - Yes N - No Index advised Y - Yes N - No Reason code I1 - Record selection I2 - Ordering/Grouping I3 - Record selection and Ordering/Grouping I4 - Nested loop join Key elds for index advised Key elds for index created

QQJNTY

QQC22

QQJNOP

QQC23

QQIDXK QQKP

QQI2 QQKP

QQKS

QQKS

QQDSS

QQDSS

QQIDXA

QQIDXA

QQRCOD

QQRCOD

QQIDXD QQCRTK

QQIDXD QQ1000

Appendix D. Query Performance: Design Guidelines and Monitoring

375

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3003 A* A R QQQ3003 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQSTIM A QQETIM A QQRSS A QQSSIZ RENAME(QQI1) + COLHDG('Size of' + 'Sort' + 'Space') A QQPSIZ RENAME(QQI2) + COLHDG('Pool' + 'Size') A QQPID RENAME(QQI3) + COLHDG('Pool' + 'ID') A QQIBUF RENAME(QQI4) + COLHDG('Internal' + 'Buffer' + 'Length') A QQEBUF RENAME(QQI5) + COLHDG('External' + 'Buffer' + 'Length') A QQRCOD A K QQJFLD A S QQRID CMP(EQ 3003)

Figure 34. Summary record for Query Sort

Table 37. QQQ3003 - Summary record for Query Sort Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user

376

OS/400 DB2 for AS/400 Database Programming V4R3

Table 37. QQQ3003 - Summary record for Query Sort (continued) Logical Field Name | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQSTIM QQETIM QQRSS QQSSIZ QQPSIZ QQPID QQIBUF QQEBUF QQRCOD Physical Field Name QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQSTIM QQETIM QQRSS QQI1 QQI2 QQI3 QQI4 QQI5 QQRCOD Description Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level Materialized view QDT number Materialized view nested level Start timestamp End timestamp Number of rows selected or sorted Size of sort space Pool size Pool id Internal sort buffer length External sort buffer length Reason code F1 - Query contains grouping elds (GROUP BY) from more that one le, or contains grouping elds from a secondary le of a join query that cannot be reordered. F2 - Query contains ordering elds (ORDER BY) from more that one le, or contains ordering elds from a secondary le of a join query that cannot be reordered. F3 - The grouping and ordering elds are not compatible. F4 - DISTINCT was specied for the query. F5 - UNION was specied for the query. F6 - Query had to be implemented using a sort. Key length of more than 2000 bytes or more than 120 key elds specied for ordering. F7 - Query optimizer chose to use a sort rather than an access path to order the results of the query. F8 - Perform specied record selection to minimize I/O wait time.

Appendix D. Query Performance: Design Guidelines and Monitoring

377

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3004 A* A R QQQ3004 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQTLN A QQTFN A QQTMN A QQSTIM A QQETIM A QQDFVL RENAME(QQC11) + COLHDG('Default' + 'Values') A QQTMPR A QQRCOD A K QQJFLD A S QQRID CMP(EQ 3004)

Figure 35. Summary record for Temporary File

Table 38. QQQ3004 - Summary record for Temporary File Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level

378

OS/400 DB2 for AS/400 Database Programming V4R3

Table 38. QQQ3004 - Summary record for Temporary File (continued) Logical Field Name QQMATN QQMATL QQTLN QQTFN QQTMN QQSTIM QQETIM QQDFVL Physical Field Name QQMATN QQMATL QQTLN QQTFN QQTMN QQSTIM QQETIM QQC11 Description Materialized view QDT number Materialized view nested level Library File Member Start timestamp End timestamp Default values may be present in temporary Y - Yes N - No Number of rows in the temporary

QQTMPR

QQTMPR

Appendix D. Query Performance: Design Guidelines and Monitoring

379

Table 38. QQQ3004 - Summary record for Temporary File (continued) Logical Field Name QQRCOD Physical Field Name QQRCOD Description Reason code F1 - Query contains grouping elds (GROUP BY) from more that one le, or contains grouping elds from a secondary le of a join query that cannot be reordered. F2 - Query contains ordering elds (ORDER BY) from more that one le, or contains ordering elds from a secondary le of a join query that cannot be reordered. F3 - The grouping and ordering elds are not compatible. F4 - DISTINCT was specied for the query. F5 - UNION was specied for the query. F6 - Query had to be implemented using a sort. Key length of more than 2000 bytes or more than 120 key elds specied for ordering. F7 - Query optimizer chose to use a sort rather than an access path to order the results of the query. F8 - Perform specied record selection to minimize I/O wait time. F9 - File is a JLF and its join type does not match the join type specied in the query. FA - Format specied for the logical le references more than 1 physical le. FB - File is a complex SQL view requiring a temporary le to contain the the results of the SQL view.

380

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3005 A* A R QQQ3005 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQTLN A QQTFN A QQTMN A QQLCKF RENAME(QQC11) + COLHDG('Lock' + 'Indicator') A QQULCK RENAME(QQC12) + COLHDG('Unlock' + 'Request') A QQRCOD A K QQJFLD A S QQRID CMP(EQ 3005)

Figure 36. Summary record for Table Locked

Table 39. QQQ3005 - Summary record for Table Locked Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level Materialized view QDT number

Appendix D. Query Performance: Design Guidelines and Monitoring

381

Table 39. QQQ3005 - Summary record for Table Locked (continued) Logical Field Name QQMATL QQTLN QQTFN QQTMN QQLCKF Physical Field Name QQMATL QQTLN QQTFN QQTMN QQC11 Description Materialized view nested level Library File Member Successful lock indicator Y - Yes N - No Unlock request Y - Yes N - No Reason code L1 - UNION with *ALL or *CS with Keep Locks L2 - DISTINCT with *ALL or *CS with Keep Locks L3 - No duplicate keys with *ALL or *CS with Keep Locks L4 - Temporary needed with *ALL or *CS with Keep Locks L5 - System File with *ALL or *CS with Keep Locks L6 - Orderby > 2000 bytes with *ALL or *CS with Keep Locks L9 - Unknown

QQULCK

QQC12

QQRCOD

QQRCOD

382

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3006 A* A R QQQ3006 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQTLN A QQTFN A QQTMN A QQPTLN A QQPTFN A QQPTMN A QQRCOD A K QQJFLD A S QQRID CMP(EQ 3006)

Figure 37. Summary record for Access Plan Rebuilt

Table 40. QQQ3006 - Summary record for Access Plan Rebuilt Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQTLN Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level Materialized view QDT number Materialized view nested level Library

Appendix D. Query Performance: Design Guidelines and Monitoring

383

Table 40. QQQ3006 - Summary record for Access Plan Rebuilt (continued) Logical Field Name QQTFN QQTMN QQPTLN QQPTFN QQPTMN Physical Field Name QQTFN QQTMN QQPTLN QQPTFN QQPTMN Description File Member Physical library Physical le Physical member

384

OS/400 DB2 for AS/400 Database Programming V4R3

Table 40. QQQ3006 - Summary record for Access Plan Rebuilt (continued) Logical Field Name QQRCOD Physical Field Name QQRCOD Description Reason code why access plan was rebuilt A1 - A le or member is not the same object as the one referenced when the access plan was last built. Some reasons they could be different are: - Object was deleted and recreated. - Object was saved and restored. - Library list was changed. - Object was renamed. - Object was moved. - Object was overridden to a different object. - This is the rst run of this query after the object containing the query has been restored. A2 - Access plan was built to use a reusable Open Data Path (ODP) and the optimizer chose to use a non-reusable ODP for this call. A3 - Access plan was built to use a non-reusable Open Data Path (ODP) and the optimizer chose to use a reusable ODP for this call. A4 - The number of records in the le member has changed by more than 10% since the access plan was last built. A5 - A new access path exists over one of the les in the query. A6 - An access path that was used for this access plan no longer exists or is no longer valid. A7 - OS/400 Query requires the access plan to be rebuilt because of system programming changes. A8 - The CCSID of the current job is different than the CCSID of the job that last created the access plan. A9 - The value of one or more of the following is different for the current job than it was for the job that last created this access plan: - date format. - date separator. - time format. - time separator. AA - The sort sequence table specied is different than the sort sequence table that was used when this access plan was created. AB - Storage pool changed or DEGREE parameter of CHGQRYA command changed.

Appendix D. Query Performance: Design Guidelines and Monitoring

385

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3007 A* A R QQQ3007 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQTLN A QQTFN A QQTMN A QQPTLN A QQPTFN A QQPTMN A QQIDXN RENAME(QQ1000) + COLHDG('Index' + 'Names') A QQTOUT RENAME(QQC11) + COLHDG('Optimizer' + 'Timed Out') A K QQJFLD A S QQRID CMP(EQ 3007)

Figure 38. Summary record for Optimizer Timed Out

Table 41. QQQ3007 - Summary record for Optimizer Timed Out Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level

386

OS/400 DB2 for AS/400 Database Programming V4R3

Table 41. QQQ3007 - Summary record for Optimizer Timed Out (continued) Logical Field Name QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQIDXN QQTOUT Physical Field Name QQMATN QQMATL QQTLN QQTFN QQTMN QQPTLN QQPTFN QQPTMN QQ1000 QQC11 Description Materialized view QDT number Materialized view nested level Library File Member Physical library Physical le Physical member Index names Optimizer timed out Y - Yes N - No

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3008 A* A R QQQ3008 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQORGQ RENAME(QQI1) + COLHDG('Original' + 'Number' + 'of QDTs') A QQMRGQ RENAME(QQI2) + COLHDG('Number' + 'of QDTs' + 'Merged') A K QQJFLD A S QQRID CMP(EQ 3008)

Figure 39. Summary record for Subquery Processing

Appendix D. Query Performance: Design Guidelines and Monitoring

387

Table 42. QQQ3008 - Summary record for Subquery Processing Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQORGQ QQMRGQ Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQI1 QQI2 Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per QDT) QDT subquery nested level Materialized view QDT number Materialized view nested level Original number of QDTs Number of QDTs merged

388

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3010 A* A R QQQ3010 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQRCNT RENAME(QQI5) + COLHDG('Refresh' + 'Counter') A QQUDEF A QQODPI RENAME(QQC11) + COLHDG('ODP' + 'Implementation') A QQHVI RENAME(QQC12) + COLHDG('Host Variable' + 'Implementation') A QQHVAR RENAME(QQ1000) + COLHDG('Host Variable' + 'Values') A K QQJFLD A S QQRID CMP(EQ 3010)

Figure 40. Summary record for Host Variable and ODP Implementation
Table 43. QQQ3010 - Summary record for Host Variable and ODP Implementation Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQRCNT QQUDEF QQODPI Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUCNT QQRCNT QQUDEF QQC11 Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier Unique count (unique per query) Unique refresh counter User dened eld ODP implementation R - Reusable ODP (ISV) N - Nonreusable ODP (V2) - Field not used

Appendix D. Query Performance: Design Guidelines and Monitoring

389

Table 43. QQQ3010 - Summary record for Host Variable and ODP Implementation (continued) Logical Field Name QQHVI Physical Field Name QQC12 Description Host variable implementation I - Interface supplied values (ISV) V - Host variables treated as literals (V2) U - File management row positioning (UP) Host variable values

QQHVAR

QQ1000

390

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3014 A* A R QQQ3014 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQMATL A QQREST A QQEPT A QQTTIM RENAME(QQI1) + COLHDG('ODP' + 'Open' 'Time') A QQORDG A QQGRPG A QQJNG A QQJNTY RENAME(QQC22) + COLHDG('Join' + 'Type') A QQUNIN A QQSUBQ A QQHSTV A QQRCDS A QQGVNE RENAME(QQC11) + COLHDG('Query' + 'Governor' + 'Enabled') A QQGVNS RENAME(QQC12) + COLHDG('Stopped' + 'by Query' + 'Governor') A QQOPID RENAME(QQC101) + COLHDG('Query' + 'Open ID') A K QQJFLD A S QQRID CMP(EQ 3014)

Figure 41. Summary record for Generic Query Information

Table 44. QQQ3014 - Summary record for Generic Query Information Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS Description Record identication Time record was created Join eld (unique per job) Relational database name System name

Appendix D. Query Performance: Design Guidelines and Monitoring

391

Table 44. QQQ3014 - Summary record for Generic Query Information (continued) Logical Field Name QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQREST QQEPT QQTTIM QQORDG Physical Field Name QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQREST QQEPT QQI1 QQORDG Description Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per query) QDT subquery nested level Materialized view QDT number Materialized view nested level Estimated number of rows selected Estimated processing time, in seconds Time spent to open cursor, in milliseconds Ordering Y - Yes N - No Grouping Y - Yes N - No Joining Y - Yes N - No Join type - when available IN - Inner join PO - Left partial outer join EX - Exception join Union Y - Yes N - No Subquery Y - Yes N - No Host variables Y - Yes N - No Record selection Y - Yes N - No Query governor enabled Y - Yes N - No Query governor stopped the query Y - Yes N - No

QQGRPG

QQGRPG

QQJNG

QQJNG

QQJNTY

QQC22

QQUNIN

QQUNIN

QQSUBQ

QQSUBQ

QQHSTV

QQHSTV

QQRCDS

QQRCDS

QQGVNE

QQCI1

QQGVNS

QQCI2

392

OS/400 DB2 for AS/400 Database Programming V4R3

Table 44. QQQ3014 - Summary record for Generic Query Information (continued) Logical Field Name QQOPID Physical Field Name QQC101 Description Query open ID

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3018 A* A R QQQ3018 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUDEF A QQJOBT RENAME(QQC11)+ COLHDG('Job' + 'Type') A QQCMDT RENAME(QQC12) + COLHDG('Command' + 'Type') A QQJOBI RENAME(QQC301) + COLHDG('Job' + 'Info') A K QQJFLD A S QQRID CMP(EQ 3018)

Figure 42. Summary record for STRDBMON/ENDDBMON

Table 45. QQQ3018 - Summary record for STRDBMON/ENDDBMON Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER | | QQJNUM QQTHRD QQUDEF QQJOBT Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS QQJOB QQUSER QQJNUM QQI9 QQUDEF QQC11 Description Record identication Time record was created Join eld (unique per job) Relational database name System name Job name Job user Job number Thread identier User dened eld Type of job monitored C - Current J - Job name A - All

Appendix D. Query Performance: Design Guidelines and Monitoring

393

Table 45. QQQ3018 - Summary record for STRDBMON/ENDDBMON (continued) Logical Field Name QQCMDT Physical Field Name QQC12 Description Command type S - STRDBMON E - ENDDBMON Monitored job information * - Current job Job number/User/Job name *ALL - All jobs

QQJOBI

QQC301

394

OS/400 DB2 for AS/400 Database Programming V4R3

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* A* Database Monitor logical file 3019 A* A R QQQ3019 PFILE(*CURLIB/QAQQDBMN) A QQRID A QQTIME A QQJFLD A QQRDBN A QQSYS A QQJOB A QQUSER A QQJNUM A QQTHRD RENAME(QQI9) + COLHDG('Thread' + 'Identifier') A QQUCNT A QQUDEF A QQQDTN A QQQDTL A QQMATN A QQCPUT RENAME(QQI1) + COLHDG('Record' + 'Retrieval' + 'CPU Time') A QQCLKT RENAME(QQI2) + COLHDG('Record' + 'Retrieval' + 'Clock Time') A QQSYNR RENAME(QQI3) + COLHDG('Synch' + 'Reads') A QQSYNW RENAME(QQI4) + COLHDG('Synch' + 'Writes') A QQASYR RENAME(QQI5) + COLHDG('Asynch' + 'Reads') A QQASYW RENAME(QQI6) + COLHDG('Asynch' + 'Writes') A QQRCDR RENAME(QQI7) + COLHDG('Records' + 'Returned') A QQGETC RENAME(QQI8) + COLHDG('Number' + 'of GETs') A K QQJFLD A S QQRID CMP(EQ 3019)

Figure 43. Detail record for Records Retrieved

Table 46. QQQ3019 - Detail record for Records Retrieved Logical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS Physical Field Name QQRID QQTIME QQJFLD QQRDBN QQSYS Description Record identication Time record was created Join eld (unique per job) Relational database name System name

Appendix D. Query Performance: Design Guidelines and Monitoring

395

Table 46. QQQ3019 - Detail record for Records Retrieved (continued) Logical Field Name QQJOB QQUSER | | QQJNUM QQTHRD QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQCPUT QQCLKT QQSYNR QQSYNW QQASYR QQASYW QQRCDR QQGETC Physical Field Name QQJOB QQUSER QQJNUM QQI9 QQUCNT QQUDEF QQQDTN QQQDTL QQMATN QQMATL QQI1 QQI2 QQI3 QQI4 QQI5 QQI6 QQI7 QQI8 Description Job name Job user Job number Thread identier Unique count (unique per query) User dened eld QDT number (unique per query) QDT subquery nested level Materialized view QDT number Materialized view nested level CPU time to return all records, in milliseconds Clock time to return all records, in milliseconds Number of synchronous database reads Number of synchronous database writes Number of asynchronous database reads Number of asynchronous database writes Number of records returned Number of calls to retrieve records returned

396

OS/400 DB2 for AS/400 Database Programming V4R3

Appendix E. Using the DB2 for AS/400 Predictive Query Governor

The DB2 for AS/400 Predictive Query Governor (governor) can stop the initiation of a query if the querys estimated or predicted runtime (elapsed execution time) is excessive. The governor acts before a query is run instead of while a query is run. The governor can be used in any interactive or batch job on the AS/400. It can be used with all DB2 for AS/400 query interfaces and is not limited to use with SQL queries. The ability of the governor to predict and stop queries before they are started is important because: v running a long-running query and abnormally ending the query before obtaining any results is a waste of system resources. v some queries operations cannot be interrupted by the End Request (ENDRQS) CL command, option 2 on the System Request menu. The creation of a temporary keyed access path or a query using a column function without group by clause are examples of these types of query operations. It is important to not start these operations if they will take longer than the user wants to wait. The governor in DB2 for AS/400 is based on the estimated runtime for a query. If the querys estimated runtime exceeds the user dened time limit, the initiation of the query can be stopped. The time limit is user-dened and specied as a time value in seconds using the Query Time Limit (QRYTIMLMT) parameter on the Change Query Attributes (CHGQRYA) CL command. You can specify a specic value or use the QQRYTIMLMT system value by specifying a value of *SYSVAL on the QRYTIMLMT parameter. There is no SQL statement to set the limit. The governor works in conjunction with the query optimizer. When a user requests DB2 for AS/400 to run a query, the following occurs: 1. The query access plan is evaluated by the optimizer. As part of the evaluation, the optimizer predicts or estimates the runtime for the query. This helps determine the best way to access and retrieve the data for the query. 2. The estimated runtime is compared against the user-dened query time limit currently in effect for the job or user session. 3. If the predicted runtime for the query is less than or equal to the query time limit, the query governor lets the query run without interruption and no message is sent to the user. 4. If the query time limit is exceeded, inquiry message CPA4259 is sent to the user. The message states that the estimated query processing time of XX seconds exceeds the time limit of YY seconds. Note: A default reply can be established for this message so that the user does not have the option to reply to the message, and the query request is always ended. 5. If a default message reply is not used, the user chooses to do one of the following: v End the query request before it is actually run.
Copyright IBM Corp. 1997, 1998

397

v Continue and run the query even though the predicted runtime exceeds the governor time limit.

Cancelling a Query
When a query is expected to run longer than the set time limit, the governor issues inquiry message CPA4259. The user enters a C to cancel the query or an I to ignore the time limit and let the query run to completion. If the user enters C, escape message CPF427F is issued to the SQL runtime code. SQL returns SQLCODE -666.

General Implementation Considerations

When using the governor it is important to remember that the optimizers estimated runtime for the query is only an estimate. The actual query runtime could be more or less than the estimate, but the value of the two should be about the same.

User Application Implementation Considerations

The time limit specied in the CHGQRYA command for the governor is established for a job or for an interactive user session. The CHGQRYA command can also cause the governor to affect a job on the system other than the current job. This is accomplished through the JOB parameter. After the source job runs the CHGQRYA command, effects of the governor on the target job is not dependent upon the source job. The query time limit remains in effect for the duration of the job or user session, or until the time limit is changed by a CHGQRYA command. Under program control, a user could be given different query time limits depending on the application function being performed, the time of day, or the amount of system resources available. This provides a signicant amount of exibility when trying to balance system resources with temporary query requirements.

Controlling the Default Reply to the Inquiry Message

The system administrator can control whether the interactive user has the option of ignoring the database query inquiry message by using the CHGJOB CL command as follows: v If a value of *DFT is specied for the INQMSGRPY parameter of the CHGJOB CL command, the interactive user does not see the inquiry messages and the query is canceled immediately. v If a value of *RQD is specied for the INQMSGRPY parameter of the CHGJOB CL command, the interactive user sees the inquiry and must reply to the inquiry. v If a value of *SYSRPYL is specied for the INQMSGRPY parameter of the CHGJOB CL command, a system reply list is used to determine whether the interactive user sees the inquiry and whether a reply is necessary. For more information on the *SYSRPYL parameter, see the book CL Reference (Abridged). The system reply list entries can be used to customize different default replies based on user prole name, user ID, or process names. The fully qualied job name is available in the message data for inquiry message CPA4259. This will allow the keyword CMPDTA to be used to select the system reply list entry that applies to the process or user prole. The user prole name is 10 characters long and starts at position 51. The process name is 10 character long and starts at

398

OS/400 DB2 for AS/400 Database Programming V4R3

position 27. The following example will add a reply list element that will cause the default reply of C to cancel any requests for jobs whose user prole is QPGMR.
ADDRPYLE SEQNBR(56) MSGID(CPA4259) CMPDTA(QPGMR 51) RPY(C)

The following example will add a reply list element that will cause the default reply of C to cancel any requests for jobs whose process name is QPADEV0011.
ADDRPYLE SEQNBR(57) MSGID(CPA4259) CMPDTA(QPADEV0011 27) RPY(C)

Using the Governor for Performance Testing

The query governor lets you optimize performance without having to run through several iterations of the query. If the query time limit is set to zero ( QRYTIMLMT(0) ) with the CHGQRYA command, the inquiry message is always sent to the user saying the estimated time exceeds the query time limit. The programmer can prompt for message help on the inquiry message and nd the same information which one can see from the PRTSQLINF (Print SQL Information) command. Additionally, if the query is canceled, the query optimizer evaluates the access plan and sends the optimizer tuning messages to the joblog. This occurs even if the job is not in debug mode. The user or a programmer can then review the optimizer tuning messages in the joblog to see if additional tuning is needed to obtain optimal query performance. Minimal system resources are used because the actual query of the data is never actually done. If the les to be queried contain a large number of records, this represents a signicant savings in system resources.

Examples
To set or change the query time limit for the current job or user session the CHGQRYA command is run. To set the query time limit for 45 seconds you would use the following CHGQRYA command:
CHGQRYA JOB(*) QRYTIMLMT(45)

This sets the query time limit at 45 seconds. If the user runs a query with an estimated runtime equal to or less than 45 seconds the query runs without interruption. The time limit remains in effect for the duration of the job or user session, or until the time limit is changed by the CHGQRYA command. Assume that the query optimizer estimated the runtime for a query as 135 seconds. A message would be sent to the user that stated that the estimated runtime of 135 seconds exceeds the query time limit of 45 seconds. To set or change the query time limit for a job other than your current job, the CHGQRYA command is run using the JOB parameter. To set the query time limit to 45 seconds for job 123456/USERNAME/JOBNAME you would use the following CHGQRYA command:
CHGQRYA JOB(123456/USERNAME/JOBNAME) QRYTIMLMT(45)

This sets the query time limit at 45 seconds for job 123456/USERNAME/JOBNAME. If job 123456/USERNAME/JOBNAME tries to run a query with an estimated runtime equal to or less than 45 seconds the query runs without interruption. If the estimated runtime for the query is greater than 45 seconds, for example 50 seconds, a message would be sent to the user stating that
Appendix E. Using the DB2 for AS/400 Predictive Query Governor

399

the estimated runtime of 50 seconds exceeds the query time limit of 45 seconds. The time limit remains in effect for the duration of job 123456/USERNAME/JOBNAME, or until the time limit for job 123456/USERNAME/JOBNAME is changed by the CHGQRYA command. To set or change the query time limit to the QQRYTIMLMT system value, use the following CHGQRYA command:
CHGQRYA QRYTIMLMT(*SYSVAL)

The QQRYTIMLMT system value is used for the duration of the job or user session, or until the time limit is changed by the CHGQRYA command.

400

OS/400 DB2 for AS/400 Database Programming V4R3

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 in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation 500 Columbus Avenue Thornwood, NY 10594 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Software Interoperability Coordinator 3605 Highway 52 N Rochester, MN 55901-7829 U.S.A.
Copyright IBM Corp. 1997, 1998

401

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are ctitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBMs application programming interfaces.

Trademarks
The following terms are trademarks of International Business Machines Corporation in the United States, or other countries, or both: Advanced/36 Application System/400 AS/400 C/400 Client Access COBOL/400 DB2 DRDA FORTRAN/400 IBM Integrated Language Environment OfficeVision Operating System/400 OS/400 RPG/400 System/36 System/38 400

C-bus is a trademark of Corollary, Inc.

402

OS/400 DB2 for AS/400 Database Programming V4R3

Microsoft, Windows, Windows NT, and the Windows 95 logo are registered trademarks of Microsoft Corporation. Java and HotJava are trademarks of Sun Microsystems, Inc. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited. PC Direct is a registered trademark of Ziff Communications Company and is used by IBM Corporation under license. Other company, product, and service names may be trademarks or service marks of others.

Notices

403

404

OS/400 DB2 for AS/400 Database Programming V4R3

Bibliography
The following AS/400 manuals contain information you may need. The manuals are listed with their full title and base order number. When these manuals are referred to in this guide, the short title listed is used. v Backup and Recovery, SC41-5304. This manual provides information about the recovery tools available on the system, such as save and restore operations, save while active, commitment control, journal management, disk recovery operations and power loss recovery. It also provides guidelines for developing a backup and recovery strategy. It contains procedures for save and restore operations, such as saving and restoring the entire system, saving storage and restoring licensed internal code, and it provides examples of using the save and restore commands. The manual also contains procedures for data and disk recovery, such as using journal management and disk recovering operations, instructions for planning and setting up mirrored protection, and information on uninterruptible power supply. The manual contains the appendices for SRC codes, example Disaster Recovery Plan and the IPL process. v DDS Reference, SC41-5712. This manual provides the application programmer with detailed descriptions of the entries and keywords needed to describe database les (both logical and physical) and certain device les (for displays, printers, and intersystem communications function (ICF)) external to the users programs. v Data Management, SC41-5710. This guide provides the application programmer with information about using les in application programs. Included are topics on the Copy File (CPYF) command and the override commands. v Distributed Data Management, SC41-5307. This guide provides the application programmer with information about remote le processing. It describes how to dene a remote le to OS/400 distributed data management (DDM), how to create a DDM le, what le utilities are supported through DDM, and the requirements of OS/400 DDM as related to other systems. v National Language Support, SC41-5101. This guide provides the data processing manager, system operator and manager, application
Copyright IBM Corp. 1997, 1998

programmer, end user, and system engineer with information about understanding and using the national language support function on the AS/400 system. It prepares the user for planning, installing, conguring, and using the AS/400 national language support (NLS) and multilingual system. It also provides an explanation of database management of multilingual data and application considerations for a multilingual system. CL Programming, SC41-5721. This guide provides the application programmer and programmer with a wide-ranging discussion of AS/400 programming topics, including a general discussion of objects and libraries, CL programming, controlling ow and communicating between programs, working with objects in CL programs, and creating CL programs. CL Reference (Abridged), SC41-5722. This set of manuals provides the application programmer and system programmer with detailed information about all AS/400 control language (CL) and its OS/400 commands. All the non-AS/400 CL commands associated with other AS/400 licensed programs, including all the various languages and utilities are now described in other manuals that support those licensed programs. Programming Reference Summary, SX41-5720. This manual is a quick-reference of various types of summary programming information relating to OS/400 but also to RPG, SEU and SDA. Included are summaries of OS/400 object types, IBM-supplied objects, CL command list, CL command matrix, DDS keywords and monitorable error messages. Work Management, SC41-5306. This guide provides the programmer with information about how to create and change a work management environment. It also includes a description of tuning the system, collecting performance data including information on record formats and contents of the data being collected, working with system values to control or change the overall operation of the system, and a description of how to gather data to determine who is using the system and what resources are being used.

405

v Query/400 Use, SC41-5210. This guide provides the administrative secretary, business professional, or programmer with information about using AS/400 Query to get data from any database le. It describes how to sign on to Query, and how to dene and run queries to create reports containing the selected data. v Security - Basic, SC41-5301. This guide explains why security is necessary, denes major concepts, and provides information on planning, implementing, and monitoring basic security on the AS/400 system. v Security - Reference, SC41-5302. This manual tells how system security support can be used to protect the system and the data from being used by people who do not have the proper authorization, protect the data from intentional or unintentional damage or destruction, keep security information up-to-date, and set up security on the system.

v DB2 for AS/400 SQL Programming, SC41-5611. This guide provides the application programmer, programmer, or database administrator with an overview of how to design, write, run, and test SQL statements. It also describes interactive Structured Query Language (SQL). v DB2 for AS/400 SQL Reference, SC41-5612. This manual provides the application programmer, programmer, or database administrator with detailed information about Structured Query Language statements and their parameters. v IDDU Use, SC41-5704. This guide provides the administrative secretary, business professional, or programmer with information about using OS/400 interactive data denition utility (IDDU) to describe data dictionaries, les, and records to the system.

406

OS/400 DB2 for AS/400 Database Programming V4R3

Index Special Characters

*CT (contains) function and zero length literal 126 *NONE DDS function 57, 59 access path (continued) temporary keyed from keyed access path 335 from the le 335 using existing specications 25 oating point elds 25 writing to auxiliary storage 29 Access Path (ACCPTH) parameter 100, 120 access plan 327 access plan rebuilt summary record 383 ACCPTH (Access Path) parameter 100, 120 add authority 90 Add Logical File Member (ADDLFM) command DTAMBRS parameter 24, 59 selecting data members 59 using 193 Add Physical File Constraint (ADDPFCST) command 245 Add Physical File Member (ADDPFM) command 193 Add Physical File Trigger (ADDPFTRG) 262 Add Physical File Trigger (ADDPFTRG) command 256 adding logical le member 24, 59 physical le constraint 245, 249 physical le member 193 physical le trigger 256 adding a trigger 256 ADDLFM (Add Logical File Member) command DTAMBRS parameter 24, 59 using 193 ADDPFCST (Add Physical File Constraint) command 245 ADDPFM (Add Physical File Member) command 193 ADDPFTRG (Add Physical File Trigger) 262 ADDPFTRG (Add Physical File Trigger) command 256 advisor query optimizer index 351 ALCOBJ (Allocate Object) command 250 ALIAS (Alternative Name) keyword 11 ALLOCATE (Allocate) parameter 36 Allocate Object (ALCOBJ) command 250 allocating object 250 storage, method 36 Allow Copy Data (ALWCPYDTA) parameter ORDER BY eld 342 sort routine 342 Allow Delete (ALWDLT) parameter 38, 92 Allow Null (ALWNULL) keyword 11 Allow Update (ALWUPD) parameter 38, 92 alternative collating sequence arranging key elds 18 arranging key elds with SRTSEQ 19 Alternative Name (ALIAS) keyword 11 ALWCPYDTA (Allow Copy Data) parameter ORDER BY 342 sort routine 342 ALWDLT (Allow Delete) parameter 38, 92 ALWNULL (Allow Null) keyword 11 ALWUPD (Allow Update) parameter 38, 92 application program and trigger under commitment control 262 application program or trigger not under commitment control 263 arithmetic operations using OPNQRYF command date 158 time 160 timestamp 161 arrival sequence summary record 367 arrival sequence access path 302 describing 17 reading database records 174 ascending sequence arranging key elds 20 attribute database le and member 27 source le 226 specifying physical le and member 35 attributes database le and member 27 AUT (Authority) parameter 32, 91 authority add 90 data 90 deleting 90 executing 91 le and data 89 object 89 public denition 91 specifying 32 read 90 specifying 89 update 90 Authority (AUT) parameter 32, 91 auxiliary storage writing access paths to frequency 29 method 102

A
Absolute Value (ABSVAL) keyword 18, 25 ABSVAL (Absolute Value) keyword 18, 25 access method 302 data space scan 305 hashing access 318 index-from-index 317 index only access 316 key positioning 312 key selection 308 parallel data space scan 309 parallel key positioning 314 parallel key selection access method 310 parallel pre-fetch 307 parallel pre-load 317 summary table 322 access path arrival sequence describing 17 reading database records 174 attribute 37 creating 17 denition 302 describing overview 7 describing logical les 17, 45 describing physical les 17 implicit 52 journaling 220 keeping current 29 keyed sequence denition 18 ignoring 100 reading database records 175 maximum size 283 protection, system-managed 221 rebuilding actual time 218 controlling 218 how to avoid 221 reducing time 219 recovering by system 217 if the system fails 31 restoring 217 saving 217 select/omit 50 sharing 51, 52, 177 specifying delayed maintenance 29 immediate maintenance 29 rebuild maintenance 29 Copyright IBM Corp. 1997, 1998

407

auxiliary storage (continued) writing data to frequency 28 method 102

coded character set identier (CCSID) 32 coding guidelines and usages, trigger program 261 COLHDG (Column Heading) keyword 11 collection 5 Column Heading (COLHDG) keyword 11 command database processing options on 114 using output les, example 209 writing output directly to a database le 209 command, CL Add Logical File Member (ADDLFM) DTAMBRS parameter 24, 59 using 193 Add Physical File Constraint (ADDPFCST) 245 Add Physical File Member (ADDPFM) 193 Add Physical File Trigger 262 Add Physical File Trigger (ADDPFTRG) 256 ADDLFM (Add Logical File Member) DTAMBRS parameter 24, 59 using 193 ADDPFCST (Add Physical File Constraint) 245 ADDPFM (Add Physical File Member) 193 ADDPFTRG (Add Physical File Trigger) 256 ALCOBJ (Allocate Object) 250 Allocate Object (ALCOBJ) 250 Change Logical File Member (CHGLFM) 193 Change Physical File Constraint (CHGPFCST) 249 Change Physical File Member (CHGPFM) 193 Check Record Locks (CHKRCDLCK) 103 CHGLFM (Change Logical File Member) 193 CHGPFCST (Change Physical File Constraint) 249 CHGPFM (Change Physical File Member) 193 CHKRCDLCK (Check Record Locks) 103 Clear Physical File Member (CLRPFM) 195 CLOF (Close File) 187 Close File (CLOF) 187 CLRPFM (Clear Physical File Member) 195 Copy File (CPYF) adding members 193 copying to and from les 229 processing keyed sequence les 18 writing data to and from source le members 228 Copy From Import File (CPYFRMIMPF) 230

B
bibliography 405 blocked input/output improving performance with both elds 42 bracketed-DBCS data 289 buffer trigger 258 buffer, trigger eld descriptions 259 111

C
cancelling a query 398 capability database le 92 physical le 38 CCSID (Coded Character Set Identier) parameter 32 Change Logical File Member (CHGLFM) command 193 Change Physical File Constraint (CHGPFCST) command 249 Change Physical File Member (CHGPFM) command 193 Change Query Attribute (CHGQRYA) command 308 changing logical le member 193 physical le member 193 check constraints 235 Check Expiration Date (EXPCHK) parameter 102 check pending 248 dependent le restrictions 249 parent le restrictions 249 check pending constraints examining 249 Check Record Locks (CHKRCDLCK) command 103 CHGLFM (Change Logical File Member) command 193 CHGPFCST (Change Physical File Constraint) command 249 CHGPFM (Change Physical File Member) command 193 CHKRCDLCK (Check Record Locks) command 103 Clear Physical File Member (CLRPFM) command 195 clearing data from physical le members 195 CLOF (Close File) command 187 Close File (CLOF) command 187 closing le 187 CLRPFM (Clear Physical File Member) command 195 CMP (Comparison) keyword 47, 52

command, CL (continued) Copy from Query File (CPYFRMQRYF) 170 Copy Source File (CPYSRCF) 228 Copy To Import File (CPYTOIMPF) 230 CPYF (Copy File) adding members 193 copying to and from les 229 processing keyed sequence les 18 writing data to and from source le members 228 CPYFRMIMPF (Copy From Import File) 230 CPYFRMQRYF (Copy from Query File) 170 CPYSRCF (Copy Source File) 228, 229 CPYTOIMPF (Copy To Import File) 230 Create Class (CRTCLS) 178 Create Logical File (CRTLF) adding members 193 creating database les 26 creating source les 225 DTAMBRS parameter 24, 59 example 54 Create Physical File (CRTPF) 245 adding members 193 creating database les 26 creating source les 225 RCDLEN parameter 5 using, example 35 Create Source Physical File (CRTSRCPF) creating physical les 35 creating source les 225 describing data to the system 5 CRTCLS (Create Class) 178 CRTLF (Create Logical File) adding members 193 creating database les 26 creating source les 225 DTAMBRS parameter 24, 59 example 54 CRTPF (Create Physical File) 245 adding members 193 creating database les 26 creating source les 225 RCDLEN parameter 5 using, example 35 CRTSRCPF (Create Source Physical File) creating physical les 35 creating source les 225 describing data to the system 5 RCDLEN parameter 5 using, example 35 Deallocate Object (DLCOBJ) 250 Display Database Relations (DSPDBR) 16, 206 Display File Description (DSPFD) 210, 233, 258 Display File Field Description (DSPFFD) 42, 206 Display Journal (DSPJRN) 210, 215

408

OS/400 DB2 for AS/400 Database Programming V4R3

command, CL (continued) Display Message Descriptions (DSPMSGD) 189 Display Object Description (DSPOBJD) 233 Display Physical File Member (DSPPFM) 18, 197 Display Problem (DSPPRB) 210 Display Program References (DSPPGMREF) 207 Display Record Locks (DSPRCDLCK) 103 DLCOBJ (Deallocate Object) 250 DSPDBR (Display Database Relations) 16, 206 DSPFD (Display File Description) 210, 233, 258 DSPFFD (Display File Field Description) 42, 206 DSPJRN (Display Journal) 210, 215 DSPMSGD (Display Message Descriptions) 189 DSPOBJD (Display Object Description) 233 DSPPFM (Display Physical File Member) 18, 197 DSPPGMREF (Display Program References) 207 DSPPRB (Display Problem) 210 DSPRCDLCK (Display Record Locks) 103 Edit Object Authority (EDTOBJAUT) 92 EDTOBJAUT (Edit Object Authority) 92 End Journal Access Path (ENDJRNAP) 220 ENDJRNAP (End Journal Access Path) 220 Grant Object Authority (GRTOBJAUT) 92 GRTOBJAUT (Grant Object Authority) 92 Initialize Physical File Member (INZPFM) 185, 194 INZPFM (Initialize Physical File Member) 185, 194 Open Database File (OPNDBF) 119 OPNDBF (Open Database File) 119 OPNQRYF (Open Query File) 119, 121 Override with Database File (OVRDBF) 29, 97 OVRDBF (Override with Database File) 29, 97 RCLRSC (Reclaim Resources) 187 Reclaim Resources (RCLRSC) 187 Remove Member (RMVM) 194 Remove Physical File Trigger (RMVPFM) 257 Rename Member (RNMM) 194 Reorganize Physical File Member (RGZPFM) 184, 195 Retrieve Member Description (RTVMBRD) 205 Revoke Object Authority (RVKOBJAUT) 92

command, CL (continued) RGZPFM (Reorganize Physical File Member) 184, 195 RMVM (Remove Member) 194 RMVPFM (Remove Physical File Trigger) 257 RNMM (Rename Member) 194 RTVMBRD (Retrieve Member Description) 205 RVKOBJAUT (Revoke Object Authority) 92 Start Journal Access Path (STRJRNAP) 220 Start Journal Physical File (STRJRNPF) 101 Start Query (STRQRY) 197 Start SQL (STRSQL) 197 STRJRNAP (Start Journal Access Path) 220 STRJRNPF (Start Journal Physical File) 101 STRQRY (Start Query) 197 STRSQL (Start SQL) 197 command (CL) Change Query Attribute (CHGQRYA) command 308 CHGQRYA (Change Query Attribute) command 308 PRTSQLINF 399 commands Add Physical File Trigger (ADDPFTRG) 262 End Database Monitor (ENDDBMON) 349 Start Database Monitor (STRDBMON) 348 COMMIT parameter 101, 120 commitment control 101, 215 trigger and application program run under 262 trigger or application program does not under 263 trigger program 262 comparing DBCS elds 291, 293 Comparison (CMP) keyword 47, 52 CONCAT (Concatenate) keyword 39, 42 Concatenate (CONCAT) keyword 39 concatenate (CONCAT) keyword 42 concatenated eld 43 concatenating, DBCS 290 concatenation function with DBCS eld 293 considerations physical le constraint 240 referential constraint 254 constant, DBCS 289 constraint disabling 249 enabling 249 constraint rules 243 constraint states 247 constraints check 235 examining check pending 249 physical le 235 primary key 235

constraints (continued) referential 235 unique 235 constraints, referential verifying 245 contains (*CT) function and zero length literal 126 CONTIG (Contiguous Storage) parameter 36 Contiguous Storage (CONTIG) parameter 36 controlling parallel processing 346 conventions, naming 7 Copy File (CPYF) command adding members 193 copying to and from les 229 processing keyed sequence les 18 writing data to and from source le members 228 Copy From Import File (CPYFRMIMPF) command 230 Copy Source File (CPYSRCF) command 228, 229 Copy To Import File (CPYTOIMPF) command 230 copying le adding members 193 copying to and from les 229 processing keyed sequence les 18 writing data to and from source le members 229 query le 170 source le 229 correcting errors 189 CPYF (Copy File) command adding members 193 copying to and from les 229 processing keyed sequence les 18 writing data to and from source le members 228 CPYFRMIMPF (Copy From Import File) command 230 CPYSRCF (Copy Source File) command 228 CPYTOIMPF (Copy To Import File) command 230 Create Class (CRTCLS) command 178 Create Logical File (CRTLF) command adding members 193 creating database les 26 creating source les 225 DTAMBRS parameter 24, 54 example 54 Create Physical File (CRTPF) command 245 adding members 193 creating database les 26 creating source les 225 RCDLEN parameter 5 using, example 35 Create Source Physical File (CRTSRCPF) command creating physical les 35 creating source les 225 describing data to the system 5 Index

409

Create Source Physical File (CRTSRCPF) command (continued) RCDLEN parameter 5 using, example 35 creating class 178 logical le adding members 193 creating database les 26 creating source les 225 DTAMBRS parameter 24, 59 example 54 physical le 245 adding members 193 creating database les 26 creating source les 225 DTAMBRS parameter 24, 59 example 54 source physical le creating physical les 35 creating source les 225 describing data to the system 5 trigger program 258 CRTCLS (Create Class) command 178 CRTLF (Create Logical File) command adding members 193 creating database les 26 creating source les 225 DTAMBRS parameter 24, 59 example 54 CRTPF (Create Physical File) command 245 adding members 193 creating database les 26 creating source les 225 RCDLEN parameter 5 using, example 35

D
data authority 89, 90 clearing from physical le members 195 copying source le 228 describing 5 dictionary-described 4 frequency of writing to auxiliary storage 28 importing from non-AS/400 system 230 initializing in a physical le member 194 integrity considerations 85, 101 loading from non-AS/400 source le 230 recovery considerations 101, 214 reorganizing physical le member 195 source le members 233 storing 28 using default for missing records from secondary les 81 dictionary for eld reference 15 example 81 logical les to secure 93

data (continued) writing to auxiliary storage 216 data description specications (DDS) describing database le 7 logical le, example 10 physical le, example 7 using, reasons 5 Data Members (DTAMBRS) parameter reading order logical le members 59 physical le members 27 data space denition 303, 305 scan 305 data space scan access method 305 database le attributes 27 member attributes 27 processing options specied on CL commands 114 recovering after abnormal system end 222 data 214 planning 213 restoring 213 saving 213 security 89 using attribute and cross-reference information 205 database data protecting and monitoring 26 database distribution 281 database le adding members 193 attributes 27 authority types 89 basic operations 173 capabilities 92 changing attributes 199 descriptions 199 closing methods 187 sequential-only processing 114 shared in a job 107 common member operations 193 creating methods 26 using FORMAT parameter 153 describing methods 3 to the system 6 using DDS 7 displaying attributes 205 descriptions of elds in 206 information 205 relationships between 206 those used by programs 207 estimating size 284 grouping data from records 148 handling errors in a program 189 joining without DDS 140 locking considerations 295 wait time 104

database le (continued) minimum size 287 naming 98 opening commands to use 119 members 119 sequential-only processing 112 shared in a job 105 shared in an activation group 105 override 29, 98 processing options 98 protecting commitment control 101 journaling 101 recovering after IPL 223 during IPL 222 options 223 saving and restoring 213 setting a position 173 setting up 3 sharing across jobs 102 sharing in a job close 107 input/output considerations 106 open 105 open data path considerations 169 SHARE parameter 32, 104 sharing in an activation group close 107 input/output considerations 106 open 105 SHARE parameter 104 sizes maximum 283 minimum 287 specifying system where created 32 wait time for locked 32 types 27 with different record formats 123 writing the output from a command to 209 database member adding to les 193 attributes 27 managing 193 naming 98 number allowed 27 removing 194 database monitor end 349 examples 351, 355 logical le DDS 362 physical le DDS 358 start 348 database monitor performance records 350 database query performance monitoring 348 database record adding 181 deleting 184 le attributes 27 reading methods arrival sequence access path 174

410

OS/400 DB2 for AS/400 Database Programming V4R3

database record (continued) reading methods (continued) keyed sequence access path updating 180 database recovery 213 date

175

arithmetic using OPNQRYF command 158 comparison using OPNQRYF command 157 duration 157 DB2 for AS/400 query component 300 DB2 Multisystem 281 DBCS (double-byte character set) considerations 289 constant 289 eld comparing 291, 293 concatenating 290 concatenation function 293 data types 289 mapping 290 substring 291 using the concatenation function 293 wildcard function 292 DDM (distributed data management) 153 DDS database monitor logical le 362 database monitor physical le 358 DDS (data description specications) describing database le 7 logical le, example 10 physical le, example 7 using, reasons 5 Deallocate Object (DLCOBJ) command 250 deallocating object 250 Default (DFT) keyword 12, 42 default lter factors 326 dening dependent le 245 elds 145 parent le 245 denition access path 302 arrival sequence access path 302 data space 305 DB2 for AS/400 query component 300 Denition default lter factors 326 denition encoded vector 302 hashing access method 318 index-from-index access method 317 index only access method 316 key positioning access method 312 key selection access method 308 keyed sequence 302 left-most key 305 Denition miniplan 327

denition parallel data space scan method 309 parallel key positioning access method 314 parallel key selection access method 310 parallel pre-fetch access method 307 primary key 305 symmetrical multiprocessing 303 denitions data space 303 isolatable 336 delaying end-of-le processing 100 delete rules 243 Deleted Percentage (DLTPCT) parameter 37 deleted record reusing 99 deleting authority 90 database record 37, 184 dependent le dening 245 restrictions check pending 249 deriving new elds from existing elds 42 DESCEND (Descend) keyword 21 descending sequence arranging key elds 20 describing access paths for database les 17 for logical les 45 overview 7 data to the system 5 database le to the system 6 with DDS 7 logical le eld use 41 oating-point elds in 45 record format 39 with DDS, example 10 physical les with DDS example 7 record format 6 description checking for changes to the record format 29 sharing existing record format 15 using existing eld 12 descriptions trigger buffer 259 design guidelines OPNQRYF performance 299 designing additional named elds 39 les to reduce access path rebuild time 219 detail record records retrieved 395 determining auxiliary storage pool 213 commit planning 213

determining (continued) data sharing requirements 102 duplicate key values 101 existing record formats 12 eld-level security requirements 89 if multiple record types are needed in les 41 journals 214 security requirements 89 when a source statement was changed 234 which source le member was used to create an object 232 device source le using 228 DFT (Default) keyword 12, 42 dictionary-described data denition 4 disabling and enabling constraint 249 Display Database Relations (DSPDBR) command 16, 206 Display File Description (DSPFD) command 258 output le 210 relating source and objects 233 Display File Field Description (DSPFFD) command 42, 206 Display Journal (DSPJRN) command converting journal receiver entries 215 output les 210 Display Message Descriptions (DSPMSGD) command 189 Display Object Description (DSPOBJD) command 233 Display Physical File Member (DSPPFM) command 18, 197 Display Problem (DSPPRB) command 210 Display Program References (DSPPGMREF) command 207 Display Record Locks (DSPRCDLCK) command 103 displaying attributes of les 205 database relations 16, 206 descriptions of elds in a le 206 errors 189 le description 210, 233, 258 le eld description 42, 206 les used by programs 207 information about database les 205 journal 210, 215 message description 189 object description 233 physical le member 18, 197 physical le member records 197 problem 210 program reference 207 record lock 103 relationships between les on the system 206 system cross-reference les 208 displaying triggers 258 distributed data management (DDM) 153 Index

411

distribution, database 281 divide by zero handling 147 DLCOBJ (Deallocate Object) command 250 DLTPCT (Deleted Percentage) parameter 37 documentation using source les for 234 double-byte character set (DBCS) considerations 289 constant 289 eld comparing 291, 293 concatenating 290 concatenation function 293 data types 289 mapping 290 substring 291 using the concatenation function 293 using the wildcard function 292 DSPDBR (Display Database Relations) command 16, 206 DSPFD (Display File Description) command 258 output le 210 relating source and objects 233 DSPFFD (Display File Field Description) command 42, 206 DSPJRN (Display Journal) command converting journal receiver entries 215 output les 210 DSPMSGD (Display Message Descriptions) command 189 DSPOBJD (Display Object Description) command 233 DSPPFM (Display Physical File Member) command 18, 197 DSPPGMREF (Display Program References) command 207 DSPPRB (Display Problem) command 210 DSPRCDLCK (Display Record Locks) command 103 DTAMBRS (Data Members) parameter reading order logical le members 59 physical le members 27 specifying order for les or members 24 DUPKEYCHK (Duplicate Key Check) parameter 101, 120 Duplicate Key Check (DUPKEYCHK) parameter 101, 120 duplicate key eld arranging 23 preventing 22 duplicate key value 101 duplicate records in a secondary le reading 72 duration (date, time, and timestamp) 157 dynamic access path function 138 Dynamic Select (DYNSLT) keyword 50 dynamic select/omit 50

DYNSLT (Dynamic Select) keyword

50

E
Edit Code (EDTCDE) keyword 11 Edit Object Authority (EDTOBJAUT) command 92 Edit Word (EDTWRD) keyword 11 EDTCDE (Edit Code) keyword 11 EDTOBJAUT (Edit Object Authority) command 92 EDTWRD (Edit Word) keyword 11 enabling and disabling constraint 249 encoded vector 302 End Database Monitor (ENDDBMON) command 349 End Journal Access Path (ENDJRNAP) command 220 end-of-le delaying processing 100 waiting for more records 177 ENDDBMON (end database monitor) command 349 ENDJRNAP (End Journal Access Path) command 220 enforcement referential integrity 246 ensuring data integrity 85 EOF Retry Delay (EOFDLY) parameter 100 EOFDLY (EOF Retry Delay) parameter 100 error correcting 189 database le handling in programs 189 displaying 189 error messages trigger program 263 estimating le size 284 examining check pending constraints 249 example changing attributes of physical les 202 descriptions of physical les 202 closing shared les 107 complex join logical le 83 dening elds derived from existing eld denitions 145 describing elds that never appear in record format 75 logical les using DDS 10 physical les with DDS 7 extra record in secondary le 68 grouping data from database le records 148 handling missing records in secondary join les 143 implicit access path sharing 52 joining database les without DDS 140 physical le to itself 80 three or more physical les 78

example (continued) joining (continued) two physical les 61 matching records in primary and secondary les 65 performance 165 performance in star join query 345 processing nal-total only 150 unique-key 144 random access 68 reading duplicate records in secondary les 72 record missing in secondary le JDFTVAL keyword not specied 66 JDFTVAL keyword specied 66 referential integrity 242 running the OPNQRYF command 151 secondary le has multiple matches for record in primary le 67 selecting records using OPNQRYF command 127 without using DDS 127 specifying keyed sequence access path without using DDS 138 specifying key elds from different les 139 join logical le 77 star join query 345 star join query with JORDER(*FILE) 345 summarizing data from database le records 148 using command output le 209 default data for missing records from secondary les 81 join elds whose attributes are different 74 more than one eld to join les 71 examples database monitor 351, 355 governor 399 performance analysis 352, 353 executing authority 91 existing access path using 51 EXPCHK (Check Expiration Date) parameter 102 EXPDATE (Expiration Date) parameter changing logical le member 194 specifying 35, 102 expiration date checking 102 specifying 35 Expiration Date (EXPDATE) parameter changing logical le member 194 specifying 35, 102

412

OS/400 DB2 for AS/400 Database Programming V4R3

F
FCFO (First-Changed First-Out) keyword 23 FEOD (Force-End-Of-Data) operation 183 eld arranging keys 18, 20 arranging keys with SRTSEQ 19 both 42 changing in a le description, effects of 199 comparing DBCS 291, 293 concatenating 43 considerations for eld use 168 data types, DBCS 289 denition 11 deriving new from existing elds 42 describing elds that never appear in record format, example 75 oating-point in logical les 45 using logical les 41 displaying descriptions in a le 206 input only 42 join 86 join logical le 86 mapping, DBCS 290 neither 42 preventing duplicate key 22 renaming 45 specifying key, example 77 translation tables 45 substring 44 using data dictionary for reference 15 existing descriptions and reference les 12 oating point in access paths 25 logical les to describe 41 multiple key 21 eld denition derived from existing eld denitions 145 functions 11 eld reference le denition 12 FIFO (First-In First-Out) keyword 23 le adding a trigger 256 closing database sequential-only processing 114 shared in a job 107 shared in an activation group 107 copying adding members 193 copying to and from les 229 processing keyed sequence les 18 writing data to and from source le members 228 creating physical 35 creating source 225 database attributes 27 closing 187 options for processing 98

le (continued) database (continued) processing options 98 recovering options 214 recovery after IPL 223 describing database to the system 6 with DDS 7 in a job 169 logical creating 53 describing record format 39 setting up 70 naming 27 opening 119 physical creating 35 specifying attributes 35 sharing database, across jobs 102 database, in the same activation group 104 database, in the same job 32, 104 source 27 specifying member 32 text 32 le, dependent dening 245 FILE (File) parameter 98 le, parent creating 245 le description displaying 258 FILE parameter 27 le restrictions check pending 249 FILETYPE (File Type) parameter 27 lter factor, default 326 nal total-only processing 150 First-Changed First-Out (FCFO) keyword 23 First-In First-Out (FIFO) keyword 23 oating point eld use in access paths 25 FMTSLR (Format Selector) parameter 183 Force Access Path (FRCACCPTH) parameter 29, 102 Force-End-Of-Data (FEOD) operation 183 Force-Write Ratio (FRCRATIO) parameter data integrity considerations 102 database data recovery 216 specifying le and member attributes 28 FORMAT (Format) keyword 16 FORMAT (Format) parameter OPNQRYF (Open Query File) command 138 format, record logical le, describing 39 FORMAT parameter creating a le, considerations 153 Format Selector (FMTSLR) parameter 183

FRCACCPTH (Force Access Path) parameter 29, 102 FRCRATIO (Force-Write Ratio) parameter 28, 102, 216 functions affected by referential integrity 251

G
generic query information summary record 391 governor 397 *DFT 398 *RQD 398 *SYSRPYL 398 CHGQRYA 397 JOB 398 QRYTIMLMT 397 time limit 398 Grant Object Authority (GRTOBJAUT) command 92 graphic-DBCS constant 289 graphic-DBCS data 289 Group Select (GRPSLT) keyword 151 grouping data from database le records 148 performance 164 grouping optimization 337 GRPSLT (Group Select) keyword 151 GRTOBJAUT (Grant Object Authority) command 92 guidelines and usages trigger program 261

H
hash join 329 hashing access method 318 high-level language (HLL) program writing considerations 154 HLL (high-level language) program writing considerations 154 host variable and ODP implementation summary record 389

I
IBM-supplied source le 226 IDDU (interactive data denition utility) 5 ignoring keyed sequence access path 100 record format 101 implementation cost estimation 325 implicit access path sharing 52 improving performance for sort sequence 164 suggestions 85 with OPNQRYF command and keyed sequence access path 162 index 7 creating from another index 317 elds used for keys 302 Index

413

Index number of 342 index advisor query optimizer 351 index created summary record 374 index only access method 316 Inhibit Write (INHWRT) parameter 102 INHWRT (Inhibit Write) parameter 102 initial le position specifying 99 Initialize Physical File Member (INZPFM) command 185, 194 initializing data in a physical le member 194 input-only eld 42 input/output blocked 111 sequential-only processing 113 sharing les in a job 106 sharing les in an activation group 106 input parameters trigger program 258 interactive data denition utility (IDDU) 5 introducing referential constraints 241 referential integrity 241 INZPFM (Initialize Physical File Member) command 185, 194

Join Order (JORDER) parameter 140 Joined Files (JFILE) keyword 39 joining database les without DDS 140 performance 164 physical le to itself, example 80 three or more physical les, example 78 two physical les 61 two physical les, example 61 JORDER (Join Order) parameter 140 journaling access path 220 commitment control 101 denition 214 management 214 physical le 101

K
keeping access paths current 29 key eld arranging ascending sequence 18, 20 changing order 18 changing order with SRTSEQ 19 descending sequence 18, 20 maximum number, length 283 preventing duplicate 22, 23 sharing 177 specifying from different les 139 subset 177 using multiple 21 Key Field (KEYFLD) parameter 150 key positioning access method 312 key range estimate 326 key selection access method 308 keyed sequence 302 keyed sequence access path denition 18 reading database records 175 KEYFILE (Key File) parameter 195 KEYFLD (Key Field) parameter 150 keyword, DDS ABSVAL (Absolute Value) 18, 25 ALIAS (Alternative Name) 11 ALWNULL (Allow Null) 11 CMP (Comparison) 47, 52 COLHDG (Column Heading) 11 CONCAT (Concatenate) 39, 42 DESCEND (Descend) 21 DFT (Default) 12, 42 DYNSLT (Dynamic Selection) 50 EDTCDE (Edit Code) 11 EDTWRD (Edit Word) 11 FCFO (First-Changed First-Out) 23 FIFO (First-In First-Out) 23 FORMAT (Format) 16 GRPSLT (Group Select) 151 JDFTVAL (Join Default Values) 66 JDUPSEQ (Join Duplicate Sequence) 69 JFILE (Joined Files) 39 LIFO (Last-In First-Out) 23 PFILE (Physical File) 11, 39 RANGE (Range) 47

keyword, DDS (continued) REF (Reference) 12 REFACCPTH (Reference Access Path denition) 25 REFACCPTH (Reference Access Path Denition) 25, 46 REFFLD (Referenced Field) 12 RENAME (Rename) 39, 45 SIGNED (Signed) 25 SST (Substring) 42 TEXT (Text) 11 TRNTBL (Translation Table) 42, 45 UNIQUE (Unique) example 10 preventing duplicate key values 22 using 7, 11 UNSIGNED (Unsigned) 18, 25 VALUES (Values) 47

L
labeled duration 157 LANGID (Language Identier) parameter 33 language identier (LANGID) specifying 33 Last-In First-Out (LIFO) keyword 23 left-most key 305 length, record 37 Level Check (LVLCHK) parameter 29, 102 LIFO (Last-In First-Out) keyword 23 limit, time 398 limitation record format sharing 17 limitations physical le constraint 240 referential constraint 254 lock member 104 record ensuring database integrity 103 releasing 180 specifying wait time 32 record format data 104 logical le adding 23, 59 adding members 193 Change Logical File Member (CHGLFM) command 194 changing attributes 203 descriptions 203 creating Create Logical File (CRTLF) command 26 database les 26 DTAMBRS parameter 24, 54 example 54 methods 53 source les 225 with DDS 53 with more than one record format 54 describing access paths 17

J
JDFTVAL (Join Default Values) keyword 66 JDUPSEQ (Join Duplicate Sequence) keyword 69 JFILE (Joined Files) keyword 39 JOB 398 join hash 329 optimization 328 join, star performance 344 Join Default Values (JDFTVAL) keyword 66 Join Duplicate Sequence (JDUPSEQ) keyword 69 join eld denition 63 rules to remember 86 join logical le complex, example 83 considerations 61 denition 61 example 83 eld 86 matching records, case 65 reading 64 requirements 85 setting up 70 specifying select/omit statements 78 summary of rules 85 join optimization performance tips 343 predicates on WHERE clause 344 join order optimization 331

414

OS/400 DB2 for AS/400 Database Programming V4R3

logical le (continued) describing (continued) eld use 41 record format 39 with DDS, example 10 estimating size 284 eld describing use 41 join dened 61 setting up 70 omitting records 46 selecting records 46 setting up 39 sharing access path 177 logical le DDS database monitor 362 logical le member 58 LVLCHK (Level Check) parameter 102

minimum database le size 287 monitor (ENDDBMON) command, end database 349 monitoring database query performance 348 monitoring and protecting database data 26 multiple format logical le adding records 58, 182 creating 54 DTAMBRS parameter 58 retrieving records 56 Multisystem 281

Open Query File (OPNQRYF) command (continued) using (continued) to select/omit records 51 typical errors 171 Open Scope (OPNSCOPE) parameter 120 opening database le commands to use 119 members 119 sequential-only processing 112 shared in a job 105 shared in an activation group 105 query le 119, 120 operation basic database le 173 physical le member 194 OPNDBF (Open Database File) command 119 OPNID (Open File Identier) parameter 120 OPNQRYF (Open Query File) command design guidelines 299 performance guidelines 299 running, messages sent 154 using copying 170 date, time, and timestamp arithmetic 157 date, time, and timestamp comparison 156 DBCS elds 292 for more than just input 155 for random processing 161 results of a query 151 selecting records, examples 127 to select/omit records 51 typical errors 171 OPNSCOPE (Open Scope) parameter 120 optimization grouping 337 join 328 join order 331 nested loop join 328 optimizer decision-making rules 327 messages 339 operation 325 query index advisor 351 optimizer timed out summary record 386 optimizer weighting FIRSTIO 325 option database le processing 98 OPTION parameter 98, 119 ORDER BY eld ALWCPYDTA 342 OUTFILE parameter 209 output all queries that performed table scans 353 SQL queries that performed table scans 352 Index

N
29, naming database le 98 database member 98 naming conventions 7 national language support 289 NBRRCDS (Number Of Records Retrieved At Once) parameter 111 neither eld 42 nested loop join 328 Notices 401 Number Of Records Retrieved At Once (NBRRCDS) parameter 111

M
MAINT (Maintenance) parameter 29 Maintenance (MAINT) parameter 29 managing database member 193 journals 214 source le 233 MAPFLD (Mapped Field) parameter 141 Mapped Field (MAPFLD) parameter 141 maximum database le sizes 283 Maximum Number of Members (MAXMBRS) parameter 27 MAXMBRS (Maximum Number of Members) parameter 27 MBR (Member) parameter opening members 120 processing data 98 specifying member names 27 member adding to les 193 attributes 27 changing attributes 193 lock 104 logical le 58 managing 193 naming 27 number allowed in a le 27 operations common to all database les 193 removing 194 renaming 194 retrieving 206 source 27 specifying text 32 Member (MBR) parameter opening members 120 processing data 98 specifying member names 27 member description retrieving 206 message sent when OPNQRYF is run 154 messages error trigger program 263

O
object allocating 250 authority types alter 90 existence 89 management 89 operational 89 reference 90 creating from source statement in a batch job 232 deallocating 250 object authority editing 92 granting 92 revoking 92 ODP implementation and host variable summary record 389 OfficeVision 300 omitting records using logical les 46 Open Database File (OPNDBF) command 119 Open File Identier (OPNID) parameter 120 Open Query File (OPNQRYF) command running, messages sent 154 using copying 170 date, time, and timestamp arithmetic 157 date, time, and timestamp comparison 156 DBCS elds 292 for more than just input 155 for random processing 161 results of a query 151 selecting records, examples 127

415

output le Display File Description (DSPFD) command 210 Display Journal (DSPJRN) command 210 Display Problem (DSPPRB) command 210 for CL commands 209 Override with Database File (OVRDBF) command 29, 97 OVRDBF (Override with Database File) command 29, 97

P
page fault 303 parallel data space scan access method 309 parallel key positioning access method 314 parallel key selection access method 310 parallel pre-fetch access method 307 parallel pre-load index-based 317 table-based 317 parallel processing controlling in jobs (CHGQRYA command) 347 system wide (QQRYDEGREE) value 346 parameter ACCPTH (Access Path) 100, 120 ALLOCATE (Allocate) 36 ALWDLT (Allow Delete) 38, 92 ALWUPD (Allow Update) 38, 92 AUT (Authority) 32, 91 CCSID (Coded Character Set Identier) 32 COMMIT 101, 120 CONTIG (Contiguous Storage) 36 DLTPCT (Deleted Percentage) 37 DTAMBRS (Data Members) selecting 59 specifying read order 24, 27 DUPKEYCHK (Duplicate Key Check) 101, 120 EOFDLY (EOF Retry Delay) 100 EXPCHK (Check Expiration Date) 102 EXPDATE (Expiration Date) changing of physical le member 194 specifying expiration date 35, 102 FILE 27, 98 FILETYPE (File Type) 27 FMTSLR (Format Selector) 183 FORMAT 138, 153 FRCACCPTH (Force Access Path) 29, 102 FRCRATIO (Force-Write Ratio) data integrity considerations 102 database data recovery 216 specifying le and member attributes 28 INHWRT (Inhibit Write) 102 JORDER (Join Order) 140

parameter (continued) KEYFILE 195 KEYFLD (Key Field) 150 LANGID (Language Identier) 33 LVLCHK (Level Check) 29, 102 MAINT (Maintenance) 29 MAPFLD (Mapped Field) 141 MAXMBRS (Maximum Number of Members) 27 MBR (Member) opening members 120 processing data 98 specifying member names 27 NBRRCDS (Number Of Records Retrieved At Once) 111 OPNID (Open File Identier) 120 OPNSCOPE (Open Scope) 120 OPTION 98, 119 OUTFILE 209 POSITION 99, 173 QRYSLT (Query Select) 51 RCDFMT (Record Format) 16 RCDFMTLCK (Record Format Lock) 104 RCDLEN (Record Length) 5, 37 RECORDS 194 RECOVER 31 REUSEDLT (Reuse Deleted Records) 37 SEQONLY (Sequential-Only Processing) 111, 120 SHARE changing for logical les 194 improving performance 32, 104 SIZE 36 SRCFILE (Source File) 27 SRCMBR (Source Member) 27 SRCOPT (Source Update Options) 196, 229 SRCSEQ (Source Sequence Numbering) 230 SRCTYPE (Source Type) specifying source type of a member 38 SRTSEQ (Sort Sequence) 33 SYSTEM 32 TEXT 32, 194 TYPE 120 UNIT 28 WAITFILE 32, 104 WAITRCD (Wait Record) 32, 103 parameters trigger program input 258 parent le dening 245 restrictions check pending 249 parent le, dening the 245 path, access creating 17 recovering if the system fails 31 performance arithmetic expressions 345 comparisons with other database functions 168

performance (continued) considerations for sort sequence 164 general 162 examples 165 grouping, joining, and selection 164 LIKE predicate 343 monitoring 299 monitoring query 348 numeric conversion 345 OPNQRYF 299 suggestions 85 with a star join 344 performance analysis example 1 352 example 2 353 example 3 353 performance considerations 399 performance records database monitor 350 performance tools 300 PFILE (Physical File) keyword 11, 39 physical le 202 attributes 35 capabilities 38 changing attributes 200 descriptions 200 creating 35, 245 CRTPF (Create Physical File) command adding members 193 creating database les 26 creating source les 225 RCDLEN parameter 5 using, example 35 dened 35 describing access paths 17 with DDS, example 7 estimating size 284 joining three or more, example 78 to itself, example 80 two, example 61 journaling starting 101 maximum size, members and key elds 283 member size 36 members 35 reorganizing data in members 195 setting up 35 start journaling 101 using DDS to describe, example 7 existing eld descriptions 12 eld reference 12 physical le constraint adding 245, 249 considerations 240 limitations 240 physical le constraints 235 physical le DDS database monitor 358 physical le member adding 193

416

OS/400 DB2 for AS/400 Database Programming V4R3

physical le member (continued) changing 194 clearing data 195 displaying records 197 initializing data 185, 194 reorganizing data 183, 195 specifying attributes 35 physical le trigger adding 256 removing 257 planning database recovery 213 position, setting in a le 173 POSITION parameter 99, 173 pre-fetching 305 predicates generated through transitive closure 336 Predictive Query Governor 397 preventing duplicate key value 22 jobs from changing data in the le 102 primary le denition 63 primary key 305 primary key constraints 235 problems join query performance 337 processing database le, options 98 DDM les 153 nal total-only 150 options 98 options specied on CL commands 114 random (using OPNQRYF command) 161 sequential-only 111 type of, specifying 98 unique-key 144 program creating trigger 258 displaying the les used by 207 handling database le errors 189 trigger coding guidelines and usages 261 using source les in 230 protecting le commitment control 101 journaling 101 protecting and monitoring database data 26 protection system-managed access-path 221 PRTSQLINF 399 public authority denition 91 specifying 32

query cancelling 398 starting 197 Query Denition Template (QDT) 327 query le copying 170 opening 120 query optimizer index advisor 351 query performance monitoring 348 Query Select (QRYSLT) parameter 51 query sort summary record 376 query time limit 398

record format (continued) data locks 104 describing example 6 logical le 39 description 15 ignoring 101 sharing existing 15 using different 123 existing 122 Record Format (RCDFMT) parameter

16

R
random access 68 random processing (using OPNQRYF) 161 RANGE (Range) keyword 47 RCDFMT (Record Format) parameter 16 RCDFMTLCK (Record Format Lock) parameter 104 RCDLEN (Record Length) parameter 5, 37 RCLRSC (Reclaim Resources) command 187 reading authority 90 database record, methods arrival sequence access path 174, 175 keyed sequence access path 176, 177 duplicate records in secondary les, example 72 join logical le 64 rebuilding access path 218 Reclaim Resources (RCLRSC) command 187 record adding 181 arranging 153 deleting 37, 184 displaying in a physical le member 197 length 37 lock integrity 103 releasing 180 reading database 174 physical le 174 reusing deleted 99 specifying length 100 wait time for locked 32 updating 180 record format checking changes to the description (LVLCHK parameter) 29 if the description changed, considerations 170 creating a logical le with more than one 54

Record Format Lock (RCDFMTLCK) parameter 104 record format relationships 17 record format sharing limitation 17 Record Length (RCDLEN) parameter 5, 37 record lock checking 103 displaying 103 record selection method 302 records database monitor performance 350 RECORDS parameter 194 records retrieved detail record 395 RECOVER parameter 31 recovering 213 access path by the system 217 after system end 222 data 214 database le after IPL 223 recovery access path if the system fails 31 database le during IPL 222 options table 223 planning 213 transaction 215 reducing access path rebuild time 219 REF (Reference) keyword 12 REFACCPTH (Reference Access Path Denition) keyword 25, 46 Reference (REF) keyword 12 Reference Access Path Denition (REFACCPTH) keyword 25, 46 Referenced Field (REFFLD) keyword 12 referential constraint considerations 254 limitations 254 referential constraints 235, 241 verifying 245 referential integrity 241 example 242 functions affected 251 simple example 242 terminology 241 referential integrity enforcement 246 REFFLD (Referenced Field) keyword 12 relationships record format 17 Index

Q
QDT (Query Denition Template) 327 QQRYTIMLMT 397 QRYSLT (Query Select) parameter 51

417

releasing locked records 180 Remove Member (RMVM) command 194 Remove Physical File Trigger (RMVPFM) command 257 removing members from les 194 physical le trigger 257 removing a trigger 257 RENAME (Rname) keyword 45 RENAME keyword 39 Rename Member (RNMM) command 194 renaming eld 45 member 194 Reorganize Physical File Member (RGZPFM) command 184, 195 reorganizing data in physical le members 184, 195 source le member data 233 restoring access path 217 data using a disk-resident save le 213 database functions 213 Retrieve Member Description (RTVMBRD) command 205 retrieving member description 206 records in a multiple format le 56 Reuse Deleted Records (REUSEDLT) parameter 37 REUSEDLT (Reuse Deleted Records) parameter 37 Revoke Object Authority (RVKOBJAUT) command 92 RGZPFM (Reorganize Physical File Member) command 184, 195 RMVM (Remove Member) command 194 RMVPFM (Remove Physical File Trigger) command 257 RNMM (Rename Member) command 194 RTVMBRD (Retrieve Member Description) command 205 rules constraint 243 delete 243 update 244 run time considerations 97, 170 summary 114 support 300 RVKOBJAUT (Revoke Object Authority) command 92

saving (continued) les and related objects 213 secondary le denition 63 example 67 handling missing records in join 143 using default data for missing records 81 security database 89 specifying authority 32, 89 select/omit access path 50 dynamic 50 selecting record using logical les 46 using OPNQRYF command 127 without using DDS, example 127 selection performance 164 SEQONLY (Sequential-Only Processing) parameter 111, 120 sequence access path arrival 17 keyed 18 sequential-only processing 111 close considerations 114 input/output considerations 113 open considerations 112 SEQONLY parameter 111, 120 Sequential-Only Processing (SEQONLY) parameter 111, 120 setting position in le 173 setting query time limit 399 setting up database le 3 join logical le 70 logical le 39 physical le 35 SEU (source entry utility) 228 SHARE (Share) parameter changing for logical les 194 improving performance 32, 104 sharing access path 177 le across jobs 102 in the same activation group 104 in the same job 32, 104 OPNQRYF command 169 implicit access path 52 record format descriptions that exist 15 sharing limitation record format 17 SIGNED (Signed) keyword 25 simple referential integrity example 242 SIZE parameter 36 SMAPP (system-managed access-path protection) 221 sort sequence performance considerations 164 specifying 33 Sort Sequence (SRTSEQ) parameter 33 source entry utility (SEU) 228

S
saving access path 217 data using a disk-resident save le 213 database functions 213

source le attributes changing 233 types 226 concepts 225 copying data 228 creating commands 225 object 231 with DDS 27, 228 without DDS 227 entering data 228 importing from non-AS/400 system 230 loading from non-AS/400 system 230 maintaining data 228 managing 233 sequence numbers used in copies 229 statements, determining when changed 234 supplied by IBM 226 using device 228 for documentation 234 in a program 230 Source File (SRCFILE) parameter 27 source le member determining which used to create an object 232 reorganizing data 233 Source Member (SRCMBR) parameter 27 source physical le creating RCDLEN parameter 5 source les 225 using, example 35 Source Sequence Numbering (SRCSEQ) parameter 230 source type specifying 38 Source Type (SRCTYPE) parameter specifying 38 Source Update Options (SRCOPT) parameter 196, 229 specications using existing access path 25 specifying access path maintenance levels 29 attributes physical le and member 35 authority 89 database le text 32 member text 32 delayed maintenance, access path 29 expiration date of a le 35, 102 le text 32 how a le is shared 102 immediate maintenance, access path 29 initial le position 99 key eld from different les 139 in join logical les, example 77

418

OS/400 DB2 for AS/400 Database Programming V4R3

specifying (continued) keyed sequence access path without DDS 138 LANGID (Language Identier) 33 language identier 33 maximum number of members 27 maximum size of a le 283 member attributes 35 member text 32 members, physical les 35 physical le and member attributes 35 physical le attributes 35 public authority 32 rebuild maintenance, access path 29 rebuilt access paths 218 record length 37, 100 select/omit statements in join logical les 78 sort sequence 33 source type of a member 38 SRTSEQ (Sort Sequence) parameter 33 system where the le is created 32 type of processing 98 wait time for a locked le or record 32 SQL (DB2 for AS/400 Structured Query Language) 5 SQL (Structured Query Language) 197 SQL information summary record 363 SRCFILE (Source File) parameter 27 SRCMBR (Source Member) parameter 27 SRCOPT (Source Update Options) parameter 196, 229 SRCSEQ (Source Sequence Numbering) parameter 230 SRCTYPE (Source Type) parameter specifying 38 SRTSEQ (Sort Sequence) parameter 33 SST (Substring) keyword 42 star join performance 344 star join query example 345 with JORDER(*FILE) parameter 345 Start Database Monitor (STRDBMON) command 348 Start Journal Access Path (STRJRNAP) command 220 Start Journal Physical File (STRJRNPF) command 101 Start Query (STRQRY) command 197 Start SQL (STRSQL) command 197 starting journal access path 220 journaling physical le 101 query 197 SQL program 197 states constraint 247 storage allocating 36 specifying location 28

storage (continued) writing access path to auxiliary 29 data to auxiliary 28, 216 STRDBMON (Start Database Monitor) command 348 STRDBMON/ENDDBMON commands summary record 393 STRJRNAP (Start Journal Access Path) command 220 STRJRNPF (Start Journal Physical File) command 101 STRQRY (Start Query) command 197 STRSQL (Start SQL) command 197 Structured Query Language (DB2 for AS/400 SQL) 5 Structured Query Language (SQL) 197 subquery processing summary record 388 Substring (SST) keyword 42 substring eld SST (Substring) keyword 44 using 44 substring operation DBCS 291 SST (Substring) keyword 44 using 44 summary database le maximums 283 locks 295 rules for join logical les 85 run time 114 summary records access plan rebuilt 383 arrival sequence 367 generic query information 391 host variable and ODP implementation 389 index created 374 optimizer timed out 386 query sort 376 SQL information 363 STRDBMON/ENDDBMON commands 393 subquery processing 388 table locked 381 temporary le 378 using existing index 371 symmetrical multiprocessing 303 system-managed access-path protection (SMAPP) 221 SYSTEM parameter 32

text specifying database le 32 database member 32 le 32 member 32 TEXT (Text) keyword 11 TEXT (Text) parameter 32, 194 time arithmetic using OPNQRYF command 160 comparison using OPNQRYF command 157 duration 157 time limits 397 timestamp arithmetic using OPNQRYF command 161 comparison using OPNQRYF command 157 duration 158 tips and techniques for OPNQRYF performance 341 transaction recovery 215 transitive closure 336 translated elds 45 Translation Table (TRNTBL) keyword 42 , 45 trigger adding 256 commitment control 262 program 262 removing 257 trigger and application program under commitment control 262 trigger buffer eld descriptions 259 trigger buffer section 258 trigger or application program not under commitment control 263 trigger program coding guidelines and usages 261 creating 258 error messages 263 input parameters 258 triggers 255 displaying 258 TRNTBL (Translation Table) keyword 42 , 45 TYPE (Type) parameter 120

U
UNIQUE (Unique) keyword example 10 preventing duplicate key values 22 using 7, 10 unique constraints 235 unique-key processing 144 UNIT parameter 28 UNSIGNED (Unsigned) keyword 18 Unsigned (UNSIGNED) keyword 18 UNSIGNED (Unsigned) keyword 25 Unsigned (UNSIGNED) keyword 25 update rules 244 updating authority 90 database record 180 Index

T
table data management methods 322 table locked summary record 381 table scans output for all queries 353 output for SQL queries 352 temporary le summary record 378 temporary keyed access path 335 terminology referential integrity 241

419

usages and guidelines trigger program 261 using Open Query File (OPNQRYF) command DBCS elds 292 wildcard function, DBCS 292 using existing index summary record 371 using JOB parameter 399

V
validation 327 VALUES (Values) keyword 47 verifying referential constraints 245

W
Wait Record (WAITRCD) parameter 103 wait time 32 32, WAITFILE (Maximum File Wait Time) parameter 32, 104 WAITRCD (Wait Record) parameter 32, 103 wildcard function denition 292 using with DBCS elds 292 writing access paths to auxiliary storage 102 data to auxiliary storage 102, 216 high-level language program 154 output from a command directly to a database le 209

Z
zero length literal and contains (*CT) function 126

420

OS/400 DB2 for AS/400 Database Programming V4R3

Readers Comments Wed Like to Hear from You

AS/400e series DB2 for AS/400 Database Programming Version 4 Publication No. SC41-5701-02 Overall, how satised are you with the information in this book? Very Satised h Satised h Neutral h Dissatised h Very Dissatised h

Overall satisfaction

How satised are you that the information in this book is: Very Satised h h h h h h Satised h h h h h h Neutral h h h h h h Dissatised h h h h h h Very Dissatised h h h h h h

Accurate Complete Easy to nd Easy to understand Well organized Applicable to your tasks

Please tell us how we can improve this book:

Thank you for your responses. May we contact you?

h Yes

h No

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.

Name Company or Organization Phone No.

Address

___________________________________________________________________________________________________

Readers Comments Wed Like to Hear from You

SC41-5701-02

Cut or Fold Along Line

Please _ _ _ _ staple Fold and _ _ _ _ _ _ _ _ _ _Fold and_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ do not_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Tape _ _ _ _ _ _ _ _ Tape NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES

BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE

IBM CORPORATION ATTN DEPT 542 IDCLERK 3605 HWY 52 N ROCHESTER MN 55901-7829

________________________________________________________________________________________ Fold and Tape Please do not staple Fold and Tape

SC41-5701-02

Cut or Fold Along Line

Printed in the United States of America on recycled paper containing 10% recovered post-consumer ber.

SC41-5701-02

Spine information:

AS/400e series

OS/400 DB2 for AS/400 Database Programming V4R3

Version 4

SC41-5701-02