z/OS Version 2 Release 3 DFSMS Object Access Method Application Programmer’s Reference IBM SC23-6865-30 Note Before using this information and the product it supports, read the information in “Notices” on page 97. This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions. Last updated: 2019-06-24 © Copyright International Business Machines Corporation 1986, 2019. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures.................................................................................................................. v Tables................................................................................................................. vii About this book.................................................................................................... ix Major divisions of this book.........................................................................................................................ix Required product knowledge......................................................................................................................ix z/OS information...........................................................................................................................................x How to read syntax diagrams.......................................................................................................................x How to send your comments to IBM.....................................................................xiii If you have a technical problem................................................................................................................xiii Summary of changes............................................................................................xv Summary of changes for z/OS Version 2 Release 3 (V2R3)...................................................................... xv Summary of changes for z/OS Version 2 Release 2 (V2R2)..................................................................... xvi Summary of changes for z/OS Version 2 Release 1 (V2R1)..................................................................... xvi Chapter 1. Understanding the Object Access Method.............................................. 1 Understanding OAM components................................................................................................................2 Establishing a storage management policy.................................................................................................2 Understanding the OAM application programming interface..................................................................... 3 Choosing data types that work well with OAM...................................................................................... 4 Retrieving a partial object...................................................................................................................... 5 Coordinating DB2, OAM, and your application...................................................................................... 5 Coordinating your application with OAM’s object identification........................................................... 5 Overriding management policy defaults................................................................................................6 Separating objects..................................................................................................................................6 Deleting objects......................................................................................................................................6 Chapter 2. Application program interface for OAM.................................................. 7 Using the OSREQ macro...............................................................................................................................7 What you can do with OSREQ.................................................................................................................7 Choosing the form.................................................................................................................................. 8 Getting the code right.............................................................................................................................8 Implementing the functions........................................................................................................................ 9 ACCESS—Initializing the OSREQ interface...........................................................................................10 CHANGE—Changing an object's management characteristics........................................................... 11 DELETE—Deleting an existing object................................................................................................... 14 QUERY—Obtaining object characteristics............................................................................................15 RETRIEVE—Retrieving an existing object............................................................................................ 18 Adding objects to the object storage hierarchy...................................................................................21 STORE function.....................................................................................................................................22 STOREBEG—Beginning a Store Sequence operation.......................................................................... 26 STOREPRT—Storing an individual part in a Store Sequence operation.............................................. 29 STOREEND—Ending a Store Sequence operation............................................................................... 31 UNACCESS—Ending the OSREQ interface........................................................................................... 33 OSREQ keyword parameter descriptions..................................................................................................33 Usage considerations.................................................................................................................................43 iii Usage requirements...................................................................................................................................44 Restrictions and limitations.......................................................................................................................44 Programming notes....................................................................................................................................45 Register use..........................................................................................................................................46 Expiration date processing........................................................................................................................ 46 Messages and codes..................................................................................................................................47 OAM return codes and reason codes...................................................................................................48 DB2 SQL error reason codes................................................................................................................ 48 CBRIBUFL macro....................................................................................................................................... 48 CBRIQEL macro......................................................................................................................................... 51 Appendix A. Sample program for object storage................................................... 57 CBROSREQ................................................................................................................................................. 57 CBROSR2....................................................................................................................................................65 CBROSR3....................................................................................................................................................73 Appendix B. Performance considerations and object data reblocking.................... 83 Performance considerations..................................................................................................................... 83 Object data reblocking......................................................................................................................... 83 Object storage...................................................................................................................................... 83 Object retrieval..................................................................................................................................... 84 Appendix C. Using the CBRUXSAE installation exit................................................85 Register contents on entry to CBRUXSAE................................................................................................. 86 Programming the CBRUXSAE exit correctly..............................................................................................87 Sample CBRUXSAE installation exit.........................................................................................................