z/OS Version 2 Release 3 MVS Programming: Resource Recovery IBM SA23-1395-30 Note Before using this information and the product it supports, read the information in “Notices” on page 629. 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-02-16 © Copyright International Business Machines Corporation 1997, 2017. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents List of Figures...................................................................................................... vii List of Tables........................................................................................................ ix About this document.............................................................................................xi Who should use this document...................................................................................................................xi How to use this document.......................................................................................................................... xi Where to find more information.................................................................................................................xii How to send your comments to IBM.....................................................................xiii If you have a technical problem................................................................................................................xiii Summary of changes...........................................................................................xiv Summary of changes V2R3....................................................................................................................... xiv Summary of changes V2R2....................................................................................................................... xiv z/OS Version 2 Release 1 summary of changes....................................................................................... xiv Chapter 1. Introducing resource recovery...............................................................1 Resource recovery programs.......................................................................................................................1 Resource recovery functions....................................................................................................................... 3 Two-phase commit protocol........................................................................................................................3 Distributed resource recovery..................................................................................................................... 7 Heuristic decisions.....................................................................................................................................15 Planning a resource manager.................................................................................................................... 16 Chapter 2. Using registration services.................................................................. 19 Registration................................................................................................................................................19 NOTIFICATION exit routine.......................................................................................................................20 Chapter 3. Using context services.........................................................................29 Contexts..................................................................................................................................................... 29 Callable services for contexts....................................................................................................................31 Context services exit routines................................................................................................................... 32 Chapter 4. Using resource recovery services.........................................................49 Resource manager states.......................................................................................................................... 49 Resource manager roles............................................................................................................................50 Resource manager failures........................................................................................................................50 Restarting...................................................................................................................................................53 Expressing interest in a UR........................................................................................................................58 Protecting the resource............................................................................................................................. 59 Protecting distributed resources...............................................................................................................65 Cascaded transactions.............................................................................................................................. 66 Local transactions......................................................................................................................................70 Unit of work identifiers.............................................................................................................................. 76 Setting exits with RRS................................................................................................................................78 Example of resource manager processing................................................................................................82 Resource recovery exit routines................................................................................................................86 RRS version information..........................................................................................................................128 Chapter 5. Callable registration services............................................................ 129 Register_Resource_Manager (CRGGRM, CRG4GRM)............................................................................. 129 iii Retrieve_Resource_Manager_Data (CRGRRMD, CRG4RRMD)............................................................... 136 Set_Exit_Information (CRGSEIF, CRGSEIF1,CRG4SEIF).......................................................................140 Unregister_Resource_Manager (CRGDRM, CRG4DRM)..........................................................................158 Chapter 6. Callable context services...................................................................163 Begin_Context (CTXBEGC, CTX4BEGC).................................................................................................. 163 Delete_Context_Interest (CTXDINT, CTX4DINT)................................................................................... 168 End_Context (CTXENDC, CTX4ENDC)..................................................................................................... 171 Express_Context_Interest (CTXEINT, CTXEINT1, CTX4EINT)...............................................................177 Retrieve_Context_Data (CTXRDTA, CTX4RDTA)..................................................................................... 185 Retrieve_Context_Interest_Data (CTXRCID, CTX4RCID).......................................................................191 Retrieve_Current_Context_Token (CTXRCC, CTX4RCC)......................................................................... 194 Set_Context_Data (CTXSDTA, CTX4SDTA)..............................................................................................198 Set_Context_Interest_Data (CTXSCID, CTXSCID2, CTX4SCID)............................................................203 Switch_Context (CTXSWCH, CTX4SWCH)...............................................................................................208 Chapter 7. Callable resource recovery services................................................... 215 Backout_Agent_UR (ATRABAK, ATR4ABAK)..........................................................................................215 Backout_UR (ATRBACK, ATR4BACK)...................................................................................................... 221 Begin_Restart (ATRIBRS, ATR4IBRS).....................................................................................................226 Begin_Transaction (ATRBEG, ATR4BEG)................................................................................................ 231 Change_Interest_Type (ATRSIT, ATR4SIT).............................................................................................236 Commit_Agent_UR (ATRACMT, ATR4ACMT).......................................................................................... 243 Commit_UR (ATRCMIT, ATR4CMIT)........................................................................................................250 Create_Cascaded_UR (ATRCCUR2, ATRCCUR3, ATR4CCUR).................................................................255 Delegate_Commit_Agent_UR (ATRADCT, ATRADCT1, ATR4ADCT)......................................................