z/OSVersion 2 Release 3

MVS Programming:Sysplex Services Guide

IBM

SA23-1400-30

Note

Before using this information and the product it supports, read the information in “Notices” on page763.

This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications untilotherwise indicated in new editions.

Last updated: 2019-02-16© Copyright International Business Machines Corporation 1994, 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

List of Figures...................................................................................................... xvList of Tables.......................................................................................................xix

About this information........................................................................................ xxiWho should use this information.............................................................................................................. xxiHow this information is organized.............................................................................................................xxiWhere to find more information................................................................................................................ xxi

How to send your comments to IBM................................................................... xxiiiIf you have a technical problem.............................................................................................................. xxiii

Summary of changes......................................................................................... xxivSummary of changes for z/OS Version 2 Release 3................................................................................xxivSummary of changes for z/OS Version 2 Release 2 (V2R2), as updated March, 2016.......................... xxvSummary of changes in z/OS Version 2 Release 2 (V2R2)......................................................................xxvSummary of changes for z/OS Version 2 Release 1 (V2R1) as updated March 2014............................ xxvz/OS Version 2 Release 1 summary of changes......................................................................................xxvi

Part 1. Introduction to Sysplex Services................................................................. 1

Chapter 1. Introduction to Sysplex Services...............................................................................................3Sysplex Services for Communication.....................................................................................................3Sysplex Services for Recovery (Automatic Restart Management)........................................................3Sysplex Services for Data Sharing..........................................................................................................3

Part 2. Sysplex Services for Communication (XCF)..................................................5

Chapter 2. Using the Cross-System Coupling Facility (XCF)....................................................................... 7XCF Concepts..........................................................................................................................................7XCF Communication Services................................................................................................................ 8

Group Services.................................................................................................................................. 9Signaling Services........................................................................................................................... 10Client/Server Services ....................................................................................................................10Status Monitoring Services.............................................................................................................11

Member Attributes............................................................................................................................... 11Permanent Status Recording..........................................................................................................12The Five Member States................................................................................................................. 12The User State Field........................................................................................................................15Member Name and Group Name....................................................................................................16The Member Token......................................................................................................................... 16The User Routines...........................................................................................................................17Member Association....................................................................................................................... 18XCF-Managed Response Collection............................................................................................... 18Providing Information to Your System Programmer......................................................................19

Summary of XCF Communication Macros........................................................................................... 19Defining Members to XCF.....................................................................................................................23Changing the Value in a User State Field.............................................................................................26

Using the IXCSETUS Macro............................................................................................................ 26Using IXCSETUS for Active Members on Different Systems..........................................................27

Using Signaling Services to Send and Receive Messages................................................................... 27What Is a Message?........................................................................................................................ 28Using the IXCMSGOX Signaling Service......................................................................................... 28

iii

Using the IXCMSGOX Macro........................................................................................................... 30Using the IXCMSGIX Macro............................................................................................................ 44Using the IXCMSGC Macro............................................................................................................. 47Handling Member Termination.......................................................................................................53Coding a Message User Routine..................................................................................................... 53Coding a Message Notify User Routine.......................................................................................... 60

Requesting XCF Status Monitoring...................................................................................................... 64Using a Status User Routine........................................................................................................... 64Updating the Status Field............................................................................................................... 70Setting and Changing a Status-Checking Interval......................................................................... 70Coding a Status User Routine......................................................................................................... 71

Notifying Members of Changes............................................................................................................ 78How XCF Works Together with the Group User Routine................................................................78Events that Cause XCF to Schedule a Group User Routine........................................................... 78Skipping of Events...........................................................................................................................82Coding a Group User Routine......................................................................................................... 85

Obtaining XCF Information.................................................................................................................. 97Obtaining Sysplex, Group, and Member Information.................................................................... 98Using the IXCQUERY Macro............................................................................................................98Obtaining Tuning and Capacity Planning Information.................................................................111

Disassociating Members from XCF.................................................................................................... 116Using the IXCQUIES Macro.......................................................................................................... 117Using the IXCLEAVE Macro...........................................................................................................117Using the IXCDELET Macro...........................................................................................................117Using the IXCTERM Macro............................................................................................................117Member Termination.................................................................................................................... 118

Example of Designing and Implementing a Multisystem Application.............................................. 119How Does PHONBOOK Work?......................................................................................................121How Does a Member Update its Status Field?.............................................................................122What Data Structures Does PHONBOOK Use?............................................................................ 122What Do the User Routines Do?................................................................................................... 123How Does the Installation Set Up PHONBOOK on Each System?...............................................127How Does PHONBOOK Handle Different Types of Work Requests?...........................................128What Happens When all Processing is Complete?...................................................................... 131What is Another Method for Designating Members?................................................................... 131

Chapter 3. Using XCF for client/server communication......................................................................... 133Overview of XCF client/server processing.........................................................................................133Defining and starting a server............................................................................................................135

Overview of IXCSRVR................................................................................................................... 135Using the IXCSEND macro................................................................................................................. 144

Overview of IXCSEND................................................................................................................... 145Content of the message ...............................................................................................................145Identity of the sender................................................................................................................... 146Time out values.............................................................................................................................146Receive bind..................................................................................................................................147Sending a request to a server.......................................................................................................147Sending a response to a client..................................................................................................... 150Summary of IXCSEND functions.................................................................................................. 151

Using the IXCRECV macro..................................................................................................................153Overview of IXCRECV................................................................................................................... 154Requesting responses and IXCRECV........................................................................................... 154Receiving responses and IXCRECV.............................................................................................. 154Processing responses...................................................................................................................154Answer area.................................................................................................................................. 154Data area.......................................................................................................................................155Storage considerations for answer and data areas..................................................................... 156Storage keys..................................................................................................................................156

iv

Target/response states ................................................................................................................156Message completion and time out values ...................................................................................157Blocking receives..........................................................................................................................157Message completion and IXCMSGC.............................................................................................158Obtaining message status............................................................................................................ 158Obtaining detailed response status ............................................................................................ 158Delivered response ...................................................................................................................... 158Competing receives ..................................................................................................................... 159Combining IXCRECV invocations................................................................................................. 159Response codes and the target receiver......................................................................................159Summary of IXCRECV function.................................................................................................... 159

Using the XCF Server..........................................................................................................................160Using the IXCREQ macro..............................................................................................................161Sending a request to the XCF Server............................................................................................161Receiving responses from the XCF Server................................................................................... 162XCF Server SERVERINFO requests.............................................................................................. 162Example of a client/server application........................................................................................ 162

Client/server compatibility................................................................................................................ 164Overview of client/server compatibility processing.................................................................... 164Setting up client/server compatibility..........................................................................................164Using the CLIENTLEVEL and CRITERIA keywords on IXCSEND................................................. 165Server upgrade............................................................................................................................. 165

Server and client recovery considerations........................................................................................ 166Server exit failures ....................................................................................................................... 166Server failures ..............................................................................................................................166Receiver failures .......................................................................................................................... 167

Coding a server exit routine............................................................................................................... 167Environment..................................................................................................................................167Entry Specifications......................................................................................................................168Return Specifications....................................................................................................................169User Routine Processing...............................................................................................................169Programming Considerations.......................................................................................................170User Routine Recovery................................................................................................................. 171Work area considerations.............................................................................................................171

Part 3. Sysplex Services for Recovery (Automatic Restart Management).............. 173

Chapter 4. Using the Automatic Restart Management Function of XCF................................................ 175Understanding How Your Installation Uses Automatic Restart Management................................. 175

Requesting Automatic Restart Management Services................................................................ 176Understanding How MVS Handles Restart Processing................................................................177

Designing Your Application to Use Automatic Restart Management Services.................................178Registering as an Element (IXCARM REQUEST=REGISTER).......................................................179Indicating Readiness for Work (IXCARM REQUEST=READY)......................................................180Deregistering the Element (IXCARM REQUEST=DEREGISTER)..................................................181Waiting for Other Work to be Restarted (IXCARM REQUEST=WAITPRED).................................181Associating One Element with Another (IXCARM REQUEST=ASSOCIATE)................................ 182Designing an Event Exit................................................................................................................ 182Gathering Statistical Data.............................................................................................................184Monitoring Restarts through the ENFREQ Macro........................................................................ 184Displaying Information about Automatic Restart Management................................................. 185IBM-Supplied Automatic Restart Manager Policy Levels............................................................ 186

Example of Using the IXCARM Macro................................................................................................187

Part 4. Sysplex Services for Data Sharing (XES).................................................. 195

Chapter 5. Introduction to Sysplex Services for Data Sharing (XES)..................................................... 197

v

Data Sharing Concepts and Terminology.......................................................................................... 198The Coupling Facility from the Point of View of the Programmer.....................................................199

Types of Coupling Facility Structures...........................................................................................199Using Sysplex Services for Data Sharing......................................................................................200Guide to Sysplex Services Topics.................................................................................................202

Chapter 6. Connection Services.............................................................................................................. 203Overview of Connection Services...................................................................................................... 203

Authorizing Coupling Facility Requests........................................................................................204Structure Concepts............................................................................................................................ 205

Defining the Structure Attributes................................................................................................. 205Identifying Connection States......................................................................................................205Understanding Connection Persistence and Structure Persistence........................................... 207

Allocating a Structure in a Coupling Facility......................................................................................208Specifying the Required Coupling Facility Attributes.................................................................. 209Selecting a Coupling Facility for Structure Allocation................................................................. 215Coupling Facility Considerations When Allocating a Structure................................................... 218Coupling Facility Resource Allocation “Rules”............................................................................ 219Successful Completion of Structure Allocation........................................................................... 221

Connecting to a Coupling Facility Structure...................................................................................... 222Overview of Connect Processing..................................................................................................222Specifying structure attributes for all structures.........................................................................228Connecting to a Cache Structure..................................................................................................230Connecting to a List Structure...................................................................................................... 233Connecting to a Lock Structure.................................................................................................... 237Using the IXLCSP Service to Determine Structure Size or Attributes......................................... 240Defining the Required Exit Routines............................................................................................ 241Determining the Success of a Connection................................................................................... 242Receiving Answer Area Information............................................................................................ 243Handling Failed Attempts to Connect to a Structure...................................................................247Understanding the Structure Version Numbers.......................................................................... 250Reconnecting to a Structure.........................................................................................................251Connecting to a Structure During User-Managed Rebuild.......................................................... 253Connecting to a Structure During User-Managed Duplexing Rebuild......................................... 253Connecting to a structure during a system-managed process....................................................254Connecting to a Structure That Is Being Altered......................................................................... 254Connecting to a Structure when a Synchronization Point Is Set.................................................255Dumping Considerations.............................................................................................................. 255Handling a Connection's Abnormal Termination......................................................................... 255Deleting Persistent Structures..................................................................................................... 260Deleting Failed-Persistent Connections.......................................................................................260Using IXLFORCE or the SETXCF FORCE Command..................................................................... 261

Structure Rebuild Processing............................................................................................................ 262Initiating a structure rebuild process...........................................................................................265Overview of user-managed rebuild processing........................................................................... 266User-Managed Rebuild Events and the Event Exit...................................................................... 270Starting the User-Managed Rebuild Process............................................................................... 272Connecting to the New Structure.................................................................................................274Working with structures in the Duplex Established Phase..........................................................282Working with structures in the Async Duplex Established phase............................................... 283Stopping a Duplexing Rebuild to Forward Complete...................................................................284Completing the User-Managed Rebuild Process......................................................................... 284Stopping a User-Managed Rebuild Process.................................................................................285Handling New Connections During a User-Managed Rebuild Process....................................... 287Handling Disconnections During Rebuilding................................................................................288Handling Failed Connections During Rebuilding..........................................................................288Handling Rebuild Connect Failures.............................................................................................. 289Handling Failures during Duplexing Rebuild................................................................................290

vi

MVS-Initiated Rebuild Processing................................................................................................292Dumping Considerations.............................................................................................................. 294Summary of User-Managed Structure Rebuild Processing......................................................... 294User-Managed Rebuild Timeline..................................................................................................296Summary of User-Managed Duplexing Rebuild Process............................................................. 296User-Managed Duplexing Rebuild Timeline.................................................................................298Summary of Rebuild and Duplexing Rebuild Stop Processing.................................................... 298Overview of System-Managed Rebuild Processing..................................................................... 299Completing or Continuing the System-Managed Process........................................................... 310Working with Structures in a Duplex Established Phase.............................................................311Working with structures in the Async Duplex Established phase............................................... 312Stopping the System-Managed Rebuild Process.........................................................................312Stopping a System-Managed Duplexing Rebuild.........................................................................313Handling Connection Changes During System-Managed Processing......................................... 313Handling Loss of Connectivity during System-Managed Processing.......................................... 316Handling structure failure during system-managed processes.................................................. 318Dumping Considerations during System-Managed Processes................................................... 319Some comparisons between user-managed and system-managed duplexing rebuild............. 319Summary of System-Managed Rebuild Processing.....................................................................320System-Managed Rebuild Timeline............................................................................................. 321Summary of System-Managed Duplexing Rebuild Processing................................................... 321System-Managed Duplexing Rebuild Timeline............................................................................322

Altering a Coupling Facility Structure................................................................................................ 322Overview of Structure Alter Processing....................................................................................... 322Starting the Structure Alter Process............................................................................................ 325Completing the Structure Alter Process...................................................................................... 327Handling New Connections during Alter Processing................................................................... 330

Responding to Connection Events.....................................................................................................331Using IXLYEEPL to Provide a Response....................................................................................... 332Using IXLYEEPL and the IXLEERSP macro...................................................................................332Events Reported to the Event Exit................................................................................................333

Using IXLUSYNC to Coordinate Processing of Events.......................................................................341Overview of IXLUSYNC Processing.............................................................................................. 342Handling Connection Failures during Synchronization................................................................343

Disconnecting from a Coupling Facility Structure............................................................................. 344Overview of Disconnect Processing............................................................................................. 344Coding the IXLDISC Macro........................................................................................................... 344Disconnect Events and the Event Exit..........................................................................................344Persistence Considerations..........................................................................................................345Dumping Considerations.............................................................................................................. 347Successful Completion of a Disconnection..................................................................................347

Forcing the Deletion of a Coupling Facility Object............................................................................ 348Deleting a Coupling Facility Structure..........................................................................................348Deleting a Coupling Facility Connection to a Structure............................................................... 348Deleting a Structure Dump........................................................................................................... 349Deleting Structure Dump Serialization.........................................................................................349Authorizing the Use of IXLFORCE................................................................................................ 349Forcing a Structure with Failed-Persistent Connections............................................................. 349

Coding Exit Routines for Connection Services.................................................................................. 350Coding the Event Exit....................................................................................................................350Using IXLEERSP............................................................................................................................352

Chapter 7. Using Cache Services (IXLCACHE)........................................................................................ 355Benefits of Using Cache Services...................................................................................................... 355Elements of A Cache System............................................................................................................. 355Elements of a Cache Structure.......................................................................................................... 357Important Terms................................................................................................................................ 359Using the Cache Structure................................................................................................................. 361

vii

Store-in Cache.............................................................................................................................. 361Store-through Cache.................................................................................................................... 362Directory-only Cache.................................................................................................................... 362

Summary of IXLCACHE Requests...................................................................................................... 363Cache Structure Allocation and Connection......................................................................................365Accessing and Managing Data Within a Cache System.....................................................................367

Managing Local Cache Buffers..................................................................................................... 367Identifying a Data Item to the Cache Structure...........................................................................368Changing a Data Item in the Cache Structure..............................................................................369Casting out Data or Updating Permanent Storage.......................................................................370

Maintaining Data Consistency............................................................................................................371Registering Interest in a Data Item and Validating Local Copies................................................ 371Deregistering Interest in a Data Item and Invalidating Local Copies......................................... 373Determining the Validity of a Data Item through IXLVECTR........................................................375

Serializing and Managing Access to Shared Data..............................................................................375Using but not Updating Data in a Store-in Cache........................................................................ 376Updating Data in a Store-in cache................................................................................................376Using but not Updating Data in a Store-through Cache.............................................................. 376Updating Data in a Store-through Cache..................................................................................... 377Using but not Updating Data in a Directory-only Cache.............................................................. 377Updating Data in a Directory-only Cache.....................................................................................378

Managing Cache Structure Resources...............................................................................................378Storage Reclaim............................................................................................................................378Deleting Data Items and Reclaim Processing..............................................................................382Casting out Data Items and Reclaim Processing.........................................................................382Measuring Cache Structure Resource Usage...............................................................................383

Understanding Synchronous and Asynchronous Cache Operations................................................ 384The MODE Parameter — Summary...............................................................................................385Using the IXLFCOMP Macro..........................................................................................................386Selecting a Data Buffer For a Request......................................................................................... 386

Receiving Information from a Request..............................................................................................392Requesting Return and Reason Codes.........................................................................................393Defining an Answer Area (ANSAREA)...........................................................................................393Determining Valid Information in the Answer Area.....................................................................393

Specifying the Vector Entry Index on IXLCACHE Requests.............................................................. 393Using Filters for Names on Requests................................................................................................ 394Restarting a Request that Ends Prematurely.................................................................................... 395

Using the Restart Token............................................................................................................... 395Using an Index Value.................................................................................................................... 396Understanding the Cache Data Entry Version Number............................................................... 397

Other Services Used with IXLCACHE.................................................................................................398WRITE_DATA: Writing a Data Item to a Cache Structure..................................................................399

IXLCACHE Functions for REQUEST=WRITE_DATA......................................................................400WRITE_DATALIST:Writing Multiple Data Items to a Cache Structure..............................................408

IXLCACHE Functions for WRITE_DATALIST.................................................................................409READ_DATA: Reading a Data Item from a Cache Structure..............................................................413

IXLCACHE Functions for REQUEST=READ_DATA........................................................................ 414REG_NAMELIST: Registering Interest in a List of Data Items.......................................................... 418

IXLCACHE Functions for REQUEST=REG_NAMELIST................................................................. 419CASTOUT_DATA: Casting Out Data from a Cache Structure............................................................. 424

Reasons for Casting out Data....................................................................................................... 424Cast-out Requests........................................................................................................................ 424IXLCACHE Functions for CASTOUT_DATA....................................................................................425

CASTOUT_DATALIST: Casting Out a List of Data Items.................................................................... 428IXLCACHE Functions for REQUEST=CASTOUT_DATALIST.......................................................... 428

UNLOCK_CASTOUT: Releasing Cast-Out Locks.................................................................................430IXLCACHE Functions for REQUEST=UNLOCK_CASTOUT............................................................ 431

UNLOCK_CO_NAME: Releasing a Single Cast-Out Lock....................................................................435

viii

IXLCACHE Functions for REQUEST=UNLOCK_CO_NAME............................................................436DELETE_NAME: Deleting Data Items From a Cache Structure.........................................................438

IXLCACHE Functions for REQUEST=DELETE_NAME................................................................... 439DELETE_NAMELIST: Deleting a List of Data Items........................................................................... 442

IXLCACHE Functions for REQUEST=DELETE_NAMELIST............................................................442CROSS_INVAL: Invalidating Other Users' Copies of Data Items...................................................... 444

Timing and CROSS_INVAL Requests........................................................................................... 445IXLCACHE Functions for REQUEST=CROSS_INVAL.................................................................... 445

CROSS_INVALLIST: Invalidating a List of Data Items.......................................................................446IXLCACHE Functions for REQUEST=CROSS_INVALLIST.............................................................447

SET_RECLVCTR: Overriding or Restoring the Default Reclaim Algorithm........................................ 448Defining the Reclaim Vector......................................................................................................... 448IXLCACHE Functions for REQUEST=SET_RECLVCTR...................................................................449

PROCESS_REFLIST: Marking Data Items as Referenced..................................................................453IXLCACHE Functions for REQUEST=PROCESS_REFLIST............................................................ 454

RESET_REFBIT: Marking Data Items as Unreferenced.....................................................................455IXLCACHE Functions for REQUEST=RESET_REFBIT...................................................................455

READ_DIRINFO: Reading Cache Directory Entries........................................................................... 457IXLCACHE Functions for REQUEST=READ_DIRINFO.................................................................. 458

READ_COCLASS: Reading A Cast-Out Class......................................................................................460IXLCACHE Functions for REQUEST=READ_COCLASS..................................................................461

READ_COSTATS: Reading Cast-Out Class Statistics..........................................................................463IXLCACHE Functions for REQUEST=READ_COSTATS.................................................................. 464

READ_STGSTATS: Reading Storage Class Statistics..........................................................................467IXLCACHE Functions for REQUEST=READ_STGSTATS................................................................ 467

Coding a Complete Exit for IXLCACHE...............................................................................................470Information Passed to the Complete Exit....................................................................................470Environment..................................................................................................................................470Input Specifications......................................................................................................................471Return Specifications....................................................................................................................471Programming Considerations.......................................................................................................471

Managing Cache Structure Utilization............................................................................................... 472Detecting When a Cache Structure Is Becoming Full..................................................................473Responding When the Structure Is Getting Full.......................................................................... 473

Chapter 8. Using List Services (IXLLIST)................................................................................................ 475List Structure Concepts......................................................................................................................476

What is a List Structure?...............................................................................................................477How Is Data Maintained in a List Structure?................................................................................479What Functions Does the List Structure Provide?....................................................................... 480Referencing List Entries................................................................................................................483Understanding the List Cursor......................................................................................................488Understanding List Structure Monitoring.....................................................................................500Understanding the Event Queue.................................................................................................. 501Understanding Event Monitor Controls........................................................................................502Understanding Sublist Monitoring................................................................................................503Reviewing Sublist and Event Queue Monitoring.......................................................................... 504Understanding List Entry Controls............................................................................................... 505Understanding List Controls.........................................................................................................505Understanding the List Authority Value....................................................................................... 507Understanding the User Exits.......................................................................................................507Understanding Synchronous and Asynchronous List Operations............................................... 508Understanding the Serialized List Structure................................................................................ 510Understanding the List Entry Version Number............................................................................ 517Selecting the Buffer Format......................................................................................................... 518

WRITE: Writing to a List Entry............................................................................................................524Understanding the Write Operation............................................................................................. 524Passing Data for a WRITE Request.............................................................................................. 526

ix

Requesting a Lock Operation as Part of a WRITE Request..........................................................526Updating an Existing List Entry.....................................................................................................526Creating a New List Entry............................................................................................................. 527Receiving Answer Area Information from a WRITE Request...................................................... 528

READ, READ_MULT, READ_LIST: Reading List Entries...................................................................... 531READ: Reading a Single List Entry................................................................................................531READ_LIST: Reading Multiple List Entries from a List................................................................. 534READ_MULT: Reading Multiple List Entries from One or More Lists............................................541

MOVE: Moving a List Entry................................................................................................................. 544Understanding the MOVE Operations.......................................................................................... 544Moving a List Entry Without Performing a Read or Write Operation........................................... 547Performing a Read Operation as Part of a Move Request............................................................547Performing a Write Operation as part of a MOVE Request.......................................................... 548Creating a New List Entry as Part of a MOVE Request.................................................................548Receiving Answer Area Information from a MOVE Request........................................................548

DELETE, DELETE_MULT, DELETE_ENTRYLIST: Deleting List Entries............................................... 551DELETE: Deleting a Single List Entry............................................................................................ 551DELETE_MULT: Deleting Multiple List Entries..............................................................................554DELETE_ENTRYLIST: Deleting a List of Entries........................................................................... 556

READ_LCONTROLS: Reading List Controls........................................................................................ 558Obtaining List Monitoring Information.........................................................................................559Receiving Answer Area Information from a READ_LCONTROLS Request.................................. 559

WRITE_LCONTROLS: Writing List Controls....................................................................................... 560Changing the List Limit................................................................................................................. 561Effect of Structure Alter on the List Limit.....................................................................................561Receiving Answer Area Information from a WRITE_LCONTROLS Request................................ 562

LOCK: Performing a Lock Operation.................................................................................................. 562Selecting the Lock Operation....................................................................................................... 562Handling an Incompletely Processed LOCK Request that Specifies LOCKOPER=READNEXT...563Receiving Answer Area Information from a LOCK Request.........................................................563

MONITOR_LIST: Monitoring List Transitions.....................................................................................564The List Notification Vector.......................................................................................................... 565Indicating Your Interest in List Transition Monitoring................................................................. 565Starting Transition Monitoring of a List........................................................................................ 565Stopping Transition Monitoring of a List.......................................................................................566Design Considerations for Using the List Transition Exit.............................................................566Receiving Answer Area Information from a MONITOR_LIST Request....................................... 567

MONITOR_EVENTQ: Monitoring an Event Queue............................................................................. 568Steps to Set Up Event Queue Transition Monitoring....................................................................568Indicating Your Interest in Event Queue Transition Monitoring..................................................568Starting Transition Monitoring of an Event Queue.......................................................................569Stopping Transition Monitoring of an Event Queue..................................................................... 569Receiving Answer Area Information from a MONITOR_EVENTQ Request................................. 569

MONITOR_SUBLIST, MONITOR_SUBLISTS: Monitoring Sublists.....................................................569Understanding the Event Queue.................................................................................................. 570Indicating Your Interest in Sublist Transition Monitoring............................................................570Specifying User Notification Controls.......................................................................................... 570MONITOR_SUBLIST: Monitoring a Single Sublist........................................................................ 570Starting Transition Monitoring of a Sublist...................................................................................570Stopping Transition Monitoring of a Sublist................................................................................. 571Scenario for Monitoring a Sublist................................................................................................. 571Receiving Answer Area Information from a MONITOR_SUBLIST Request.................................571MONITOR_SUBLISTS: Monitoring Multiple Sublists....................................................................572Receiving Answer Area Information from a MONITOR_SUBLISTS Request.............................. 573

READ_EMCONTROLS: Reading Event Monitor Controls....................................................................573Receiving Answer Area Information from a READ_EMCONTROLS Request............................... 574

READ_EQCONTROLS: Reading Event Queue Controls......................................................................574Obtaining Event Queue Monitoring Information..........................................................................574

x

Receiving Answer Area Information from a READ_EQCONTROLS Request............................... 575DEQ_EVENTQ: Retrieving Events from the Event Queue.................................................................. 575

Handling an Incompletely Processed DEQ_EVENTQ Request.................................................... 576Receiving Answer Area Information from a DEQ_EVENTQ Request...........................................576

Coding a Complete Exit......................................................................................................................576Information Passed to the Complete Exit....................................................................................576Environment..................................................................................................................................577Input Specifications......................................................................................................................577Return Specifications....................................................................................................................578

Coding a Notify Exit............................................................................................................................ 579Information Passed to the Notify Exit..........................................................................................579Environment..................................................................................................................................580Input Specifications......................................................................................................................580Return Specifications....................................................................................................................581

Coding a List Transition Exit...............................................................................................................581Information Passed to the List Transition Exit.............................................................................582Environment..................................................................................................................................582Input Specifications......................................................................................................................582Return Specifications....................................................................................................................583

Managing List Structure Utilization....................................................................................................583Detecting When a List Structure Is Becoming Full...................................................................... 584Responding When the Structure is Getting Full...........................................................................585

Enhancements to Sublist Monitoring.................................................................................................586

Chapter 9. Using List Services (IXLLSTE, IXLLSTM, IXLLSTC)................................................................587Additional List Services Provided by IXLLSTE, IXLLSTM, and IXLLSTC............................................587

Understanding Program-Specified Entry Identifiers................................................................... 588Enhancement to List Services Entry Key and Secondary Key Comparison.................................588Enhancements to List Monitoring.................................................................................................588Understanding Secondary Keys................................................................................................... 589Using the New List Services Request Types................................................................................ 589Specifying 64-bit buffers..............................................................................................................590

Comparing IXLLSTC, IXLLSTE, and IXLLSTM with IXLLIST.............................................................. 590Locating a List Entry......................................................................................................................590Specifying a Range of Values........................................................................................................590Specifying Entry Keys or Secondary Keys....................................................................................591Identifying Individual List Entries for IXLLSTM Requests........................................................... 591

IXLLSTE: List Structure Single Entry Services................................................................................... 591Selecting an Entry for Processing by IXLLSTE............................................................................. 591Receiving Answer Area Information............................................................................................ 593Creating a List Entry......................................................................................................................593Reading a List Entry...................................................................................................................... 594Writing a List Entry........................................................................................................................594Moving a List Entry........................................................................................................................595Deleting a List Entry......................................................................................................................597

IXLLSTM: List Structure Multiple Entry Services...............................................................................597Selecting Entries for Processing by IXLLSTM.............................................................................. 598Receiving Answer Area Information............................................................................................ 599Restarting IXLLSTM Requests...................................................................................................... 599Reading List Entries from a List....................................................................................................599Deleting List Entries from a List....................................................................................................601Reading List Entries from Multiple Lists.......................................................................................603Deleting List Entries from Multiple Lists...................................................................................... 603Moving a List of List Entries.......................................................................................................... 604Deleting a List of List Entries........................................................................................................ 606

IXLLSTC: List Structure Control Services.......................................................................................... 607Understanding Threshold Counts................................................................................................ 608Reading Control Information for a List.........................................................................................609

xi

Updating Control Information for a List....................................................................................... 609Monitoring a List........................................................................................................................... 610Monitoring a Sublist......................................................................................................................611Monitoring a Set of Sublists..........................................................................................................611Monitoring a List by Keyrange Values.......................................................................................... 612Monitoring an Event Queue.......................................................................................................... 613Reading EMC Control Information............................................................................................... 614Reading Event Queue Control Information..................................................................................614Dequeuing Event Monitor Controls from an Event Queue...........................................................614Performing Lock Operations.........................................................................................................615Reading Structure Counts for a List Structure ............................................................................ 615

Chapter 10. Using Lock Services (IXLLOCK)........................................................................................... 617Resource Concepts............................................................................................................................ 617

What Is a Resource?..................................................................................................................... 617State of a Resource Request Queue.............................................................................................618

What can you do with the XES lock services?................................................................................... 619Managing Contention......................................................................................................................... 620

Defining a Protocol to Handle Contention....................................................................................621How is Contention Resolved?.......................................................................................................621Sample Locking Protocol — Definition......................................................................................... 622Sample Locking Protocol — Implementation...............................................................................624

Informing a User of Request Completion.......................................................................................... 625Using the IXLLOCK MODE Parameter.......................................................................................... 625Asynchronous duplexing.............................................................................................................. 626

Lock Structure Concepts....................................................................................................................626The Lock Table.............................................................................................................................. 627Record data entries...................................................................................................................... 633Size Considerations for a Lock Structure..................................................................................... 633

Recovery Considerations................................................................................................................... 635Designing for recovery..................................................................................................................635XES cleanup processing............................................................................................................... 636Sample Recovery Protocol........................................................................................................... 637

Requesting Lock Services.................................................................................................................. 639Requesting Ownership of a Resource (REQUEST=OBTAIN)....................................................... 639Determining the Completion of an OBTAIN Request.................................................................. 641Changing Ownership Attributes (REQUEST=ALTER)................................................................... 641Determining the Completion of an ALTER Request..................................................................... 642Releasing ownership of a resource (REQUEST=RELEASE)..........................................................643Determining the Completion of a RELEASE Request...................................................................643Processing multiple resource requests (REQUEST=PROCESSMULT)......................................... 644Determining the completion of a PROCESSMULT request.......................................................... 645

Using Exits for Coupling Facility Lock Services................................................................................. 645General Requirements..................................................................................................................646Coding a Complete Exit................................................................................................................ 648Coding a Contention Exit.............................................................................................................. 650Coding a Notify Exit...................................................................................................................... 659Using the Synchronous Update Service (IXLSYNCH).................................................................. 661

Using the Lock Cleanup and Recovery Service (IXLRT).................................................................... 663Identifying the User......................................................................................................................663Providing areas for returned data................................................................................................ 663Identifying the Record Data......................................................................................................... 664Assigning a Record Data Type to the Record Data.......................................................................664What You Can Request with IXLRT...............................................................................................664Handling an incompletely processed IXLRT request.................................................................. 667

Chapter 11. Supplementary List, Lock, and Cache Services.................................................................. 669Using the IXLFCOMP Macro............................................................................................................... 669

xii

Issuing IXLFCOMP During Recovery Processing......................................................................... 669Purging a Coupling Facility Operation................................................................................................670

Handling Operations in Progress..................................................................................................670Handling Operations Yet to be Processed................................................................................... 670Timing Considerations..................................................................................................................670

Using the IXLVECTR Macro................................................................................................................ 670List Notification Vector................................................................................................................. 670Local Cache Vector....................................................................................................................... 672

Using the IXLADUPX macro............................................................................................................... 678

Chapter 12. Using Note Pad Services (IXCNOTE)...................................................................................681Note pad concepts and terminology................................................................................................. 683

Use of the term connection.......................................................................................................... 684Designing your application to use an XCF Note Pad....................................................................685

What is a note.....................................................................................................................................687Note name.....................................................................................................................................687Note instance number.................................................................................................................. 688Note tags.......................................................................................................................................688Note content................................................................................................................................. 689Note connection identifier............................................................................................................690Note persistence...........................................................................................................................690

What is an XCF Note Pad....................................................................................................................691Note pad name............................................................................................................................. 692Note pad description.................................................................................................................... 695Note pad information....................................................................................................................695Note limit...................................................................................................................................... 695Duplexing preference................................................................................................................... 696Note pad protocols....................................................................................................................... 696Timestamp when created.............................................................................................................699

What is a connection.......................................................................................................................... 699Connection token..........................................................................................................................700Connection identifier.................................................................................................................... 700Connection description................................................................................................................ 700Connection information................................................................................................................701Access scope................................................................................................................................ 701Connection scope......................................................................................................................... 701Usage classification...................................................................................................................... 701Termination scope........................................................................................................................ 704

Using the IXCNOTE macro................................................................................................................. 705Answer area.................................................................................................................................. 706System Authorization Facility (SAF) requirements......................................................................707Use of a connection token............................................................................................................ 708Quiescing conditions.................................................................................................................... 708Constrained conditions.................................................................................................................709Timeout conditions.......................................................................................................................710Status unknown conditions.......................................................................................................... 711XCF component failures............................................................................................................... 713

Note pad requests..............................................................................................................................714Create note pad............................................................................................................................ 714Query note pad............................................................................................................................. 715Delete note pad............................................................................................................................ 717

Connection requests.......................................................................................................................... 719Create connection.........................................................................................................................720Delete connection.........................................................................................................................721Pause connection......................................................................................................................... 721Resume paused connection......................................................................................................... 722

Single note requests.......................................................................................................................... 722Overview....................................................................................................................................... 722

xiii

Create note................................................................................................................................... 726Replace note................................................................................................................................. 726Write note..................................................................................................................................... 727Read note......................................................................................................................................727Delete note................................................................................................................................... 728

Multi-note requests............................................................................................................................728Overview....................................................................................................................................... 729Multi-note selection criteria......................................................................................................... 729Concurrent request issues........................................................................................................... 731Read notes.................................................................................................................................... 732Delete notes..................................................................................................................................735

Note pad related limits...................................................................................................................... 736Buffer size and single note requests............................................................................................737Buffer size and multi-note requests............................................................................................ 737

Chapter 13. Coupling Facility Accounting and Measuring Services....................................................... 739Using IXLMG.......................................................................................................................................739

Specifying the information level...................................................................................................739Types of information available..................................................................................................... 740Defining an Output Area............................................................................................................... 742Programming Considerations.......................................................................................................743Specifying the Information To Be Returned by IXLMG................................................................743

Chapter 14. Dumping Services for Coupling Facility Structures............................................................ 747Using the IHABLDP Macro................................................................................................................. 747Using the IXLZSTR Macro.................................................................................................................. 747

Requesting Structure Information............................................................................................... 747Receiving Information Returned by the IXLZSTR Macro.............................................................748

Using Component Data in the Dump Data Set.................................................................................. 748Associating Macros with the Data Types..................................................................................... 750

Chapter 15. Documenting your Coupling Facility Requirements........................................................... 755Specifying the Coupling Facility Structure Requirements................................................................ 755

Naming the Structure................................................................................................................... 755Determining the Structure Size.................................................................................................... 755Providing an Exclusion List........................................................................................................... 756Understanding the Persistence Attribute.................................................................................... 756Specifying the Rebuild and/or Alter Attribute..............................................................................756Providing Connectivity Requirements..........................................................................................756

Specifying the coupling facility requirements...................................................................................757Summarizing Your Requirements...................................................................................................... 757

Appendix A. Accessibility...................................................................................759Accessibility features.............................................................................................................................. 759Consult assistive technologies................................................................................................................ 759Keyboard navigation of the user interface.............................................................................................. 759Dotted decimal syntax diagrams.............................................................................................................759

Notices..............................................................................................................763Terms and conditions for product documentation................................................................................. 764IBM Online Privacy Statement................................................................................................................ 765Policy for unsupported hardware............................................................................................................765Minimum supported hardware................................................................................................................766Programming Interface Information.......................................................................................................766Trademarks.............................................................................................................................................. 766

Index................................................................................................................ 767

xiv

List of Figures

1. Systems, Groups, and Members in an XCF Sysplex..................................................................................... 82. XCF Member States.....................................................................................................................................153. Address Space Restrictions for XCF Macros...............................................................................................214. Sending a Message from One Member to Another.....................................................................................285. Example of Queue of Message Data Elements...........................................................................................346. First Example of Table of Message Data Elements.................................................................................... 347. Second Example of Table of Message Data Elements............................................................................... 358. Third Example of Table of Message Data Elements................................................................................... 369. XCF Status Monitoring Service Normal Processing (Part 1 of 2)................................................................6710. XCF Status Monitoring Service Normal Processing (Part 2 of 2)............................................................. 6811. Summary of Group User Routine Logic (Part 1 of 3)................................................................................ 9212. Summary of Group User Routine Logic (Part 2 of 3)................................................................................ 9313. Summary of Group User Routine Logic (Part 3 of 3)................................................................................ 9414. PHONBOOK Multisystem Application.................................................................................................... 12115. Data Structures Used by PHONBOOK Routine.......................................................................................12316. Overview of client/server processing in the sysplex..............................................................................13417. Multiple Systems Sharing Data Through a Coupling Facility................................................................. 19918. Connection State Transitions: Undefined, Active, Disconnecting, Failing.............................................2