Table of Contents (exploded view)
Abstract for MVS Programming: Sysplex Services Guide
Summary of changes
Summary of changes for z/OS Version 2 Release 2 (V2R2), as updated March, 2016
Summary of changes in z/OS Version 2 Release 2 (V2R2)
Summary of changes for z/OS Version 2 Release 1 (V2R1) as updated March 2014
z/OS Version 2 Release 1 summary of changes
Introduction to Sysplex Services
Introduction to Sysplex Services
Sysplex Services for Communication
Sysplex Services for Recovery (Automatic Restart Management)
Sysplex Services for Data Sharing
Sysplex Services for Communication (XCF)
Using the Cross-System Coupling Facility (XCF)
XCF Concepts
XCF Communication Services
Group Services
Signaling Services
Client/Server Services
Status Monitoring Services
Member Attributes
Permanent Status Recording
The Five Member States
The Active State
The Created State
The Quiesced State
The Failed State
The Not-Defined State
The User State Field
Member Name and Group Name
The Member Token
The User Routines
Member Association
XCF-Managed Response Collection
Providing Information to Your System Programmer
Summary of XCF Communication Macros
Defining Members to XCF
Changing the Value in a User State Field
Using the IXCSETUS Macro
Example of Using the IXCSETUS Macro
Using IXCSETUS for Active Members on Different Systems
Using Signaling Services to Send and Receive Messages
What Is a Message?
Using the IXCMSGOX Signaling Service
Sending and Receiving Messages
Sending Large Messages
Saving and Discarding Messages
Broadcasting a Message to Members of a Group
Consolidating Responses to a Message
Providing Ordered Delivery of Messages
Specifying a Message Timeout Value
Using the IXCMSGOX Macro
Identifying the Sending Member
Identifying the Target Member or Members
Identifying a Single Target Member
Identifying Multiple Target Members using a Table
Creating the Table of Target Members
Maintaining the Integrity of the Table of Target Members
Sending a Message to Active Group Members
Identifying the Message Data
Sending Message Data Using a Single Buffer
Sending Message Data Using Multiple Buffers
Examples of Message Data Element Formats for Multi-Buffer Messages
Specifying the Storage Key
Supporting Asynchronous Message Access by XCF
Specifying Message Control Information
Specifying Message Response Collection
When Does XCF Not Expect a Response?
Providing a Response for XCF Response Collection
Providing a Response on Behalf of Another Member
Calling the Message Notify User Routine
Specifying the Delivery Options for Messages
Requesting Unordered Delivery
Requesting Ordered Delivery
Understanding Message Completion
Specifying a Timeout Value for Message Completion
Requesting Notification of Message Completion
Specifying Data to be Associated with the Message
Identifying the Message
Qualifying the Notification Request
Specifying the Notification Process
Handling Error Conditions
Queueing Messages for Later Delivery
Handling IXCMSGOX Requests When a Member Terminates
Using the IXCMSGIX Macro
Identifying the Message to Be Delivered
Determining the Length of the Message to be Received
Using the MEPL
Using the MNPL
Determining Message Disposition
Specifying the Storage Key
Receiving Message Data into a Single Buffer Area
Receiving Message Data into Multiple Buffers
Specifying the Message Data Elements
Specifying the Location of Each Buffer
Specifying the Location of Each ALET
Specifying the Size of Each Buffer
Specifying the Location of the Next Message Data Element
When the Message Can't Fit in the Buffer Storage Provided
Examples of Message Data Element Formats for Multi-Buffer Messages
Using the IXCMSGC Macro
Understanding the Programming Environment
Identifying the Requestor
Requesting that a Message or Response Be Saved
Identifying a Message to be Saved
Saving a Message
Saving a Partially Delivered Message
Saving a Message and its Associated Responses
Saving an Individual Response
Performance Implications
Requesting that a Message Be Discarded
Identifying the Message To Be Discarded
Cancelling a Message-Out Request
Letting the System Discard a Message
Timing Considerations
Requesting Information about Messages
Requesting Message-out Information
Requesting Message-in Information
Requesting Detail Information about a Specific Message
Retrieving Information from the Answer Area
Requesting that a Message Be Completed
Identifying the Message
Replacing the User Data
Requesting that a User Routine Is To Process a Message
Identifying the Message
Identifying the User Routine
Passing Information to the User Routine
Handling Member Termination
Coding a Message User Routine
Environment
Restrictions
Entry Specifications
Return Specifications
User Routine Processing
Programming Considerations
User Routine Recovery
Timing Considerations
Coded Example
Coding a Message Notify User Routine
Environment
Restrictions
Entry Specifications
Return Specifications
User Routine Processing
User Routine Recovery
Requesting XCF Status Monitoring
Using a Status User Routine
Normal Processing
Checking for Status Update Missing
Checking for Status Update Resumed
Summary of Important Concepts
Events Other than Normal Processing
Updating the Status Field
Setting and Changing a Status-Checking Interval
Coding a Status User Routine
User Routine Environment
User Routine Recovery
User Routine Processing
Programming Considerations
Restrictions
Timing
Entry Specifications
Registers at Entry
Parameter List Contents
Return Specifications
Registers on Exit
Return Codes
Coded Example
Checking for status update missing
Checking for status update resumed
Notifying Members of Changes
How XCF Works Together with the Group User Routine
Events that Cause XCF to Schedule a Group User Routine
Skipping of Events
Events That XCF Might Skip
Determining When Events Are Skipped
User State Field Design Considerations
Coding a Group User Routine
User Routine Environment
User Routine Recovery
User Routine Processing
Programming Considerations
Restrictions
Timing
Entry Specifications
Registers at Entry
Parameter List Contents
Return Specifications
Coded Example
If the GEPLMISR and GEPLMISD flags are both off
If either the GEPLMISR flag or the GEPLMISD flag is on
Obtaining XCF Information
Obtaining Sysplex, Group, and Member Information
Using the IXCQUERY Macro
Specifying the Information Level
Specifying the Type of Information
Programming Considerations
Information Mapped by the IXCYQUAA Mapping Macro
Information Returned Inline to IXCQUERY
Obtaining Tuning and Capacity Planning Information
Handling the X‘4’ Reason Code
Retrieving Information from the Answer Area
Specifying the Information Level
Specifying the System from which You Gather the Information
Specifying the Type of Information
Disassociating Members from XCF
Using the IXCQUIES Macro
Using the IXCLEAVE Macro
Using the IXCDELET Macro
Using the IXCTERM Macro
Member Termination
Task Termination
Address Space Termination
Removing Systems from the Sysplex
Example of Designing and Implementing a Multisystem Application
How Does PHONBOOK Work?
How Does a Member Update its Status Field?
What Data Structures Does PHONBOOK Use?
What Do the User Routines Do?
The Message User Routine
The Status User Routine
The Group User Routine
How Does the Installation Set Up PHONBOOK on Each System?
Setting Up on System 1
Setting Up on System 2
Setting Up on System 3
How Does PHONBOOK Handle Different Types of Work Requests?
Updating the Database - Requestor is the PRIMARY Member
Updating the Database - Requestor is the NO-BACKUP Member
Finding a Name in the Database - Requestor is the BACKUP Member
Member 1 (PRIMARY) Misses its Status Update
What Happens When all Processing is Complete?
What is Another Method for Designating Members?
Using XCF for client/server communication
Overview of XCF client/server processing
Defining and starting a server
Overview of IXCSRVR
Servers and server instances
Naming a server
Obtaining information about servers
Server naming conventions
Specifying information about the server
XCF Server stub routine and the server exit routine
Server exit parameter list and processing
Initialializing the server
Providing a work area for XCF
Processing a request sent by a client
Acknowledgment of a request
Response binds
Server exit and work area storage
Defining feature strings
Specifying client/server compatibility levels
Defining response binds
Stopping servers
Startup timing issues
Summary of IXCSRVR functions
Using the IXCSEND macro
Overview of IXCSEND
Content of the message
Identity of the sender
Time out values
Receive bind
Sending a request to a server
FUNCTION keyword of IXCSEND
DESCRIPTION keyword of IXCSEND
Identifying the target server
Server selection criteria
Using EXPECTREPLY and RESPONSELEVEL
Sending a response to a client
Identify the target request
Specify additional response information
Summary of IXCSEND functions
Using the IXCRECV macro
Overview of IXCRECV
Requesting responses and IXCRECV
Receiving responses and IXCRECV
Processing responses
Answer area
Data area
One data area for all responses
One data area per response
Storage considerations for answer and data areas
Storage keys
Target/response states
Message completion and time out values
Blocking receives
Message completion and IXCMSGC
Obtaining message status
Obtaining detailed response status
Delivered response
Competing receives
Combining IXCRECV invocations
Response codes and the target receiver
Summary of IXCRECV function
Using the XCF Server
Using the IXCREQ macro
Sending a request to the XCF Server
Receiving responses from the XCF Server
XCF Server SERVERINFO requests
Example of a client/server application
Starting the server
Starting the client
Client/server compatibility
Overview of client/server compatibility processing
Setting up client/server compatibility
Using the CLIENTLEVEL and CRITERIA keywords on IXCSEND
Server upgrade
An example
Server and client recovery considerations
Server exit failures
Server failures
Receiver failures
Coding a server exit routine
Environment
Entry Specifications
Return Specifications
User Routine Processing
Programming Considerations
User Routine Recovery
Work area considerations
Sysplex Services for Recovery (Automatic Restart Management)
Using the Automatic Restart Management Function of XCF
Understanding How Your Installation Uses Automatic Restart Management
Requesting Automatic Restart Management Services
Understanding Abstract Resources
Using the IXCARM Macro
Understanding How MVS Handles Restart Processing
Restart Considerations for Abstract Resources
Establishing Security for Restarted Jobs
Designing Your Application to Use Automatic Restart Management Services
Registering as an Element (IXCARM REQUEST=REGISTER)
Specifying Restart Parameters
Indicating Readiness for Work (IXCARM REQUEST=READY)
Deregistering the Element (IXCARM REQUEST=DEREGISTER)
Waiting for Other Work to be Restarted (IXCARM REQUEST=WAITPRED)
Associating One Element with Another (IXCARM REQUEST=ASSOCIATE)
Designing an Event Exit
Exit Routine Environment
Exit Recovery
Exit Routine Processing
Processing Considerations
Input Register Information
Output Register Information
Parameter List Contents
Gathering Statistical Data
Monitoring Restarts through the ENFREQ Macro
Displaying Information about Automatic Restart Management
IBM-Supplied Automatic Restart Manager Policy Levels
Example of Using the IXCARM Macro
Sysplex Services for Data Sharing (XES)
Introduction to Sysplex Services for Data Sharing (XES)
Data Sharing Concepts and Terminology
The Coupling Facility from the Point of View of the Programmer
Types of Coupling Facility Structures
Using Sysplex Services for Data Sharing
Designing Your Application to Exploit the Coupling Facility
Managing recovery in a sysplex
Guide to Sysplex Services Topics
Connection Services
Overview of Connection Services
Authorizing Coupling Facility Requests
Structure Concepts
Defining the Structure Attributes
Identifying Connection States
Understanding Connection Persistence and Structure Persistence
Connection Persistence
Structure Persistence
Allocating a Structure in a Coupling Facility
Specifying the Required Coupling Facility Attributes
Specifying a Connectivity Requirement
Specifying a Coupling Facility Level Requirement
Identifying a Minimum Coupling Facility Level
Understanding the CFLEVEL Returned by XCF and XES Services
Specifying the Structure Size
How MVS Initially Allocates the Structure
Structure Allocation when Rebuilding a Structure
Determining Maximum Structure Size
Determining Minimum Structure Size
Determining Marginal Structure Size
Understanding Coupling Facility Volatility
Planning for Coupling Facility Failure-Independence
Creating the Exclusion List
Selecting a Coupling Facility for Structure Allocation
Preference List Order Not Enforced
Preference List Order Enforced
Using the SFM System Weights in Coupling Facility Selection
CONNECTIVITY=DEFAULT
CONNECTIVITY=BESTGLOBAL
CONNECTIVITY=SYSPLEX
Understanding Connectivity in a Mixed Sysplex Environment
Coupling Facility Considerations When Allocating a Structure
Understanding Coupling Facility Storage
Coupling Facility Resource Allocation “Rules”
CFRM Policy Specification
Authorized Application Specification
Coupling Facility Storage Constraints
Coupling Facility Storage Increment
Coupling Facility Structure ID Limit
Successful Completion of Structure Allocation
Note about designing structure connections
Connecting to a Coupling Facility Structure
Overview of Connect Processing
Naming the Structure
Naming the Connection
Specifying Connector Data
Providing a Connection Level
Requesting a Coupling Facility Level
Requesting a Minimum CFLEVEL
System-managed Processing Considerations
Specifying Coupling Facility Connectivity Requirements
Allowing User-Managed Rebuild for a Structure
Allowing the Structure to be Duplexed
Enabling Support of System-Managed Processes
Allowing the Structure to be Altered
Handling Dump Serialization
Monitoring structure repopulation
Specifying Structure Attributes for All Structures
Connecting to a Cache Structure
Selecting the Number of Data Elements and Their Size
Effect of CFLEVEL on MAXELEMNUM
Selecting the Directory-to-Element Ratio
Determining Whether to Have Adjunct Areas
Selecting the Number of Cast-Out classes
Selecting the Number of Storage Classes
Determining Whether to Have User Data Field (UDF) Order Queues
Determining Whether to Use Name Class Masks
Suppressing Certain Events for a Connector
Connecting to a List Structure
Selecting the Data Element Size
Effect of CFLEVEL on MAXELEMNUM
Requesting Storage for Event Monitor Controls
Selecting the Entry-To-Element Ratio
Deciding How to Limit the Storage Used by Each List
Determining Whether to Have Adjunct Areas
Determining Whether to Have Named or Keyed List Entries
Connecting to a Lock Structure
Determining Whether to Specify Record Data
Understanding the Resource Name Length Attribute
Determining the Number of List Structure Users
Determining the Number of Lock Entries
Determining the Number of Lock Structure Users
Determining whether to monitor internal storage for lock structures
Using the IXLCSP Service to Determine Structure Size or Attributes
Determining Structure Size and Ratios Given Structure Attributes
Determining Structure Counts Given Structure Size and Ratios
Determining Storage-Class Memory Size Given Counts and Attributes
Defining the Required Exit Routines
Event Exit
Complete Exit
Notify Exit
Contention Exit
List Transition Exit
Summary of Required Exit Routines
Determining the Success of a Connection
Receiving Answer Area Information
Successful Completion of a Connection
Verifying Structure Attributes
Cache Structure
List Structure
Lock Structure
Handling Failed Attempts to Connect to a Structure
Using ENF Event Code 35
Understanding the Structure Version Numbers
Reconnecting to a Structure
Connecting to a Structure During User-Managed Rebuild
Connecting to a Structure During User-Managed Duplexing Rebuild
Connecting to a Structure During a System-Managed Process
Connecting to a Structure That Is Being Altered
Connecting to a Structure when a Synchronization Point Is Set
Dumping Considerations
Handling a Connection's Abnormal Termination
Deleting Persistent Structures
Deleting Failed-Persistent Connections
Using IXLFORCE or the SETXCF FORCE Command
Structure Rebuild Processing
Initiating a Structure Rebuild Process
Overview of User-Managed Rebuild Processing
IXLCONN Support for User-Managed Processes
Phases for User-Managed Processes
Rebuild Quiesce Phase
Rebuild Connect Phase
Rebuild Duplex Established Phase
Rebuild Cleanup Phase
Role of CFRM Policy in the Rebuild Process
Options for Initiating Duplexing Rebuild
Automatic Duplexing
Rebuilding with a New CFRM Policy
Rebuilding without a New CFRM Policy
Rebuild Connectivity Requirements
User-Managed Rebuild Events and the Event Exit
XES Monitoring of Rebuild Event Responses
Starting the User-Managed Rebuild Process
Understanding the Rebuild Quiesce Phase
Delivery of the Rebuild Quiesce Event
Rebuild Quiesce Information Returned in IXLYEEPL
Responding to the Rebuild Quiesce Event
Completing Outstanding Structure Requests
Completing the Rebuild Quiesce Phase
Connecting to the New Structure
Understanding the Rebuild Connect Phase
Delivery of Rebuild Connect Event
Using the IXLCONN macro for rebuilds
Specifying Coupling Facility Connectivity Requirements for Rebuild Processing
Evaluating Current Connectivity Status
Handling Failed Attempts to Rebuild a Structure
Successful Completion of IXLCONN REBUILD
Handling a Failed IXLCONN REBUILD Request
Receiving Answer Area Information from IXLCONN REBUILD
Reconstructing the New Coupling Facility Structure
Delivery of the Rebuild Connects Complete Event
Completing the Rebuild Connect Phase
Working with Structures in the Duplex Established Phase
Understanding the Duplex Established Phase
Delivery of Rebuild Duplex Established Event
Stopping a Duplexing Rebuild to Forward Complete
Understanding Rebuild Stopduplex Processing to Forward Complete
Delivery of Rebuild Switch Event
Responding to the Rebuild Switch Event
Completing the User-Managed Rebuild Process
Understanding the Rebuild Cleanup Phase
Delivery of Rebuild Cleanup Event
Responding to the Rebuild Cleanup Event
Completing the Rebuild Cleanup Phase
Delivery of the Rebuild Process Complete Event
Stopping a User-Managed Rebuild Process
Understanding Rebuild Stop Processing
Delivery of Rebuild Stop Event
Responding to a Rebuild Stop Event
Handling New Connections During a User-Managed Rebuild Process
Handling Disconnections During Rebuilding
Handling Failed Connections During Rebuilding
Providing a Response for a Failed Connector
Handling Rebuild Connect Failures
Handling Failures during Duplexing Rebuild
Handling Loss of Connectivity during Duplexing Rebuild
Before the Duplex Established Phase
During the Duplex Established Phase
After the Duplex Established Phase
Handling Structure Failure
Before the Duplex Established Phase
During the Duplex Established Phase
After the Duplex Established Phase
Handling Connection Failure
Before the Duplex Established Phase
During the Duplex Established Phase
During Switch Processing and the Cleanup Phase
During Stop Processing
MVS-Initiated Rebuild Processing
How MVS Determines Whether to Initiate Structure Rebuild Processing
Reporting the Percentage of Lost Connectivity
Reporting Policy-Based Actions to Connectors
Responding to the XES Recommended Action Event
Dumping Considerations
Summary of User-Managed Structure Rebuild Processing
User-Managed Rebuild Timeline
Summary of User-Managed Duplexing Rebuild Process
User-Managed Duplexing Rebuild Timeline
Summary of Rebuild and Duplexing Rebuild Stop Processing
Overview of System-Managed Rebuild Processing
IXLCONN Support for System-Managed Processing
Phases for System-Managed Processing
Startup Phase
Quiesce
Allocate
Attach
Copy
Duplex Established
Cleanup
Role of CFRM in System-Managed Processing
MVS-Initiated Duplexing Rebuild
Events and the Event Exit for System-Managed Processing
XES Monitoring of Active Connector Event Responses
Starting the System-Managed Process
Responding to the Structure Temporarily Unavailable Event
Suspending Work Units during System-Managed Processing
Establishing the New Structure in System-Managed Process
Allocating the New Structure
Considerations for Cache Structures during System-Managed Processing
Connecting Users to the New Structure
Populating the New Structure
Completing or Continuing the System-Managed Process
Working with Structures in the Duplex Established Phase
Stopping the System-Managed Rebuild Process
Stopping a System-Managed Duplexing Rebuild
Handling Connection Changes During System-Managed Processing
New Connections
IXLYCONA Contents when Connecting during the Duplex Established Phase
Disconnecting or Failed Connections
Handling Loss of Connectivity during System-Managed Processing
Loss of Connectivity Before a System-Managed Process Is Initiated
Loss of Connectivity Before the System Commits to the New Structure
Loss of Connectivity After the System Commits to the New Structure
Loss of Connectivity During the Stop of System-Managed Processing
Handling Structure Failure during System-Managed Processes
Dumping Considerations during System-Managed Processes
Some Comparisons between User-Managed and System-Managed Duplexing Rebuild
Summary of System-Managed Rebuild Processing
System-Managed Rebuild Timeline
Summary of System-Managed Duplexing Rebuild Processing
System-Managed Duplexing Rebuild Timeline
Altering a Coupling Facility Structure
Overview of Structure Alter Processing
Changing the Structure Size
Changing the Structure Entry-to-Element Ratio
Changing the Percentage of Event Monitor Controls
Altering a Duplexed Structure
Structure Type Considerations
Starting the Structure Alter Process
Notifying Connectors of Structure Alter Initiation
Initiating Alter for a Structure with No Connectors
Initiating Alter for a Structure with Failed-Persistent Connectors
Completing the Structure Alter Process
Notifying Connectors of Structure Alter Completion
Requesting that Structure Alter Be Stopped
Structure Failure
Connection Termination
System Failure
Changes in Connectivity
Alter/Rebuild Coordination
Structure Objects in Storage-Class Memory
Altering a Structure in the Duplex Established Phase
Alter/Duplexing Coordination
Information Returned in IXLYEEPL
Detecting ENF Code 35 for Structure Alter
Handling New Connections during Alter Processing
Responding to Connection Events
Using IXLYEEPL to Provide a Response
Using IXLYEEPL and the IXLEERSP macro
Handling Outstanding Event Responses
Events Reported to the Event Exit
XES Monitoring of Event Responses
Events Monitored by XES
Information Provided by XES Event Monitoring
Connection Considerations with XES Event Monitoring
Discontinuing XES Event Monitoring
Using IXLUSYNC to Coordinate Processing of Events
Overview of IXLUSYNC Processing
Information Returned in IXLYEEPL
XES Monitoring of User Sync Point Event Responses
Handling Connection Failures during Synchronization
Disconnecting from a Coupling Facility Structure
Overview of Disconnect Processing
Coding the IXLDISC Macro
Disconnect Events and the Event Exit
Suppressing Certain Event Notifications
Retrieving Information from IXLYEEPL
Responding to a Disconnected or Failed Connection Event
XES Monitoring of Disconnected or Failed Connection Event Responses
Persistence Considerations
Normal Disconnection
Disconnection Because of Failure
Disconnection to Delete the Structure
Handling Resources for a Disconnection
Dumping Considerations
Successful Completion of a Disconnection
Forcing the Deletion of a Coupling Facility Object
Deleting a Coupling Facility Structure
Deleting a Coupling Facility Connection to a Structure
Deleting a Structure Dump
Deleting Structure Dump Serialization
Authorizing the Use of IXLFORCE
Forcing a Structure with Failed-Persistent Connections
Coding Exit Routines for Connection Services
Coding the Event Exit
Exit Routine Environment
Exit Recovery
Exit Routine Processing
Processing Considerations
Macro Instructions and Restrictions
Input Register Information
Output Register Information
Parameter List Contents
Return Specifications
Using IXLEERSP
Using Cache Services (IXLCACHE)
Benefits of Using Cache Services
Elements of A Cache System
Elements of a Cache Structure
Important Terms
Using the Cache Structure
Store-in Cache
Accessing the Data
Casting out Data from the Cache Structure
Assigning Storage Classes
Recovery
Store-through Cache
Accessing the Data
Casting out Data from the Cache Structure
Assigning storage Classes
Recovery
Directory-only Cache
Accessing the Data
Casting out Data from the Cache Structure
Assigning Storage Classes
Recovery
Sizing the Structure
Summary of IXLCACHE Requests
Cache Structure Allocation and Connection
Accessing and Managing Data Within a Cache System
Managing Local Cache Buffers
Identifying a Data Item to the Cache Structure
Reading, Writing, or Registering Interest in a Data Item
Determining the Validity of a Data Item
Defining a Storage Class for a Data Item
Changing a Data Item in the Cache Structure
Casting out Changed Data
Considerations Using the Store-through Cache Method
Considerations Using the Directory-only Cache Method
Casting out Data or Updating Permanent Storage
Considerations for Cast-out Using the Store-in Cache Method
Considerations for Cast-out Using the Store-through Cache Method
Considerations for Cast-out Using the Directory-only Cache Method
Maintaining Data Consistency
Registering Interest in a Data Item and Validating Local Copies
Maintaining Connections between the Local Cache Vector and Data Items
Registering Interest in a Data Item
Deregistering Interest in a Data Item and Invalidating Local Copies
Invalidating Local Cache Copies of a Data Item
Determining the Validity of a Data Item through IXLVECTR
Changing the Size of the Local Cache Vector
Serializing and Managing Access to Shared Data
Using but not Updating Data in a Store-in Cache
Updating Data in a Store-in cache
Using but not Updating Data in a Store-through Cache
Updating Data in a Store-through Cache
Using but not Updating Data in a Directory-only Cache
Updating Data in a Directory-only Cache
Managing Cache Structure Resources
Storage Reclaim
Assigning and Using Storage Classes
Storage Reclaim Considerations and the Directory-only Cache Method
Storage Reclaim Algorithm
Defining a Reclaim Algorithm for a Storage Class
Example of a Reclaim Vector
Rationale
How the Reclaim Vector for Storage Class 1 Works
How the Reclaim Vector for Storage Class 2 Works
Considerations when Defining the Reclaim Vector
Managing Storage Reclaim for Specific Data Items
Using PROCESS_REFLIST Requests
Deleting Data Items and Reclaim Processing
Casting out Data Items and Reclaim Processing
Assigning Cast-Out Classes
Establishing a Cast-Out Process
Releasing Cast-Out Locks
Measuring Cache Structure Resource Usage
Understanding Synchronous and Asynchronous Cache Operations
The MODE Parameter — Summary
Using the IXLFCOMP Macro
Selecting a Data Buffer For a Request
BUFFER Keyword
BUFLIST Keyword
ADJAREA
Design Considerations for Choosing the Buffer Format
Buffer Sizes
Specifying BUFFER or BUFLIST
Performance Considerations Using Buffers
Buffers and Structure Data Elements
Design Considerations for Defining Buffer Storage Areas
Defining Buffer Storage Areas for a WRITE_DATALIST Request
Determining Buffer Storage Ownership
Using Real Versus Virtual Storage
Design Considerations for Page-Fixed Storage
Specifying the Buffer Storage Key
Receiving Information from a Request
Requesting Return and Reason Codes
Defining an Answer Area (ANSAREA)
Specifying the IXLYCAA Level
Determining Valid Information in the Answer Area
Specifying the Vector Entry Index on IXLCACHE Requests
Using Filters for Names on Requests
Restarting a Request that Ends Prematurely
Using the Restart Token
Restarting Requests Multiple Times with Restart Tokens
Using an Index Value
Restarting Requests Multiple Times with Index Values
Understanding the Cache Data Entry Version Number
Setting the Cache Entry Version Number
Using the Version Number to Select Data Entries for Processing
Using the Version Number to Serialize Data Entry Operations
Other Services Used with IXLCACHE
WRITE_DATA: Writing a Data Item to a Cache Structure
IXLCACHE Functions for REQUEST=WRITE_DATA
Registering Interest in the Data Item for WRITE_DATA Requests
Using the WHENREG=YES Option
Using the WHENREG=NO Option
Using the REGUSER Options
Scenario
Specifying the Data Item Name
Specifying the Changed or Unchanged State of the Data Item
WRITE_DATA Requests and Unchanged Data
Changed Data and Storage Reclaim
Casting out Changed Data
Recovery and Changed Data Items
Obtaining the Cast-Out Lock on Write Requests
Writing Changed and Unchanged Data items to the Cache
Store-in Cache System
Store-through Cache System
Assigning a Changed Data Item to a Cast-Out Class
Specifying Parity of a Changed Data Item
Writing User-Defined Data
Assigning a Storage Class
Specifying the Size of the Data Entry to Hold the Data
Selecting the Buffering Method
Specifying Data on a Write Request
Specifying that No Data Is to Be Written on a Write Request
Specifying the Cache Entry Version Number on a WRITE_DATA Request
Receiving Answer Area Information
Defining and Writing a New Data Item: Summary
Considerations for a Store-through Cache System
Considerations for a Store-in Cache System
Specifying Storage Class and Data Element Numbers
Updating an Existing Data Item: Summary
Considerations for a Store-through Cache System
Considerations for a Store-in Cache System
Specifying Storage Class and Data Element Numbers
WRITE_DATALIST:Writing Multiple Data Items to a Cache Structure
IXLCACHE Functions for WRITE_DATALIST
Specifying the entries to be written
Providing information in the write-operation-block
Selecting a buffering method
Specifying the index values
Providing a storage area for Returned WOB processing
Situations that Cause WOB Processing to be Discontinued
Receiving answer area information
Restarting a WRITE_DATALIST request
Writing a list of data items: Summary
READ_DATA: Reading a Data Item from a Cache Structure
IXLCACHE Functions for REQUEST=READ_DATA
Specifying the Data Item Name
Registering Interest in the Data Item for READ_ DATA Requests
Specifying a New or Existing Data Item
Assigning a Storage Class
Selecting the Buffering Method
Specifying the Data to be Read
Specifying that No Data Is To Be Read
Receiving Answer Area Information
Defining a New Data Item: Summary
Reading a Data Item: Summary
REG_NAMELIST: Registering Interest in a List of Data Items
IXLCACHE Functions for REQUEST=REG_NAMELIST
Specifying a Data Item for Registration Block Processing
Specifying the Registration Block Buffer
Specifying the Index Values for Registration Block Processing
Providing a Storage Area for Returned Registration Information
Receiving Answer Area Information
Description of Returned Registration Information
Restarting a REG_NAMELIST Request that Ends Prematurely
Registering Interest in a List of Data Items: Summary
CASTOUT_DATA: Casting Out Data from a Cache Structure
Reasons for Casting out Data
Cast-out Requests
IXLCACHE Functions for CASTOUT_DATA
Specifying the Data Item Name
Registering Interest in the Data Item for CASTOUT_DATA Requests
Specifying a Process Identifier
Selecting the Buffering Method
Specifying the Data to be Cast Out
Cast out and Unchanged Data
Receiving Answer Area Information
Casting Out A Data Item: Summary
CASTOUT_DATALIST: Casting Out a List of Data Items
IXLCACHE Functions for REQUEST=CASTOUT_DATALIST
Specifying the data items to be cast-out
Specifying a Process Identifier
Selecting a Buffering Method
Understanding the Use of the Buffer Areas
Specifying the Index Values for Data Item Processing
Situations that cause CASTOUTLIST entry processing to be discontinued
Restarting a REQUEST=CASTOUT_DATALIST Request that ends prematurely
Receiving answer area information
Casting out a list of data items: Summary
UNLOCK_CASTOUT: Releasing Cast-Out Locks
IXLCACHE Functions for REQUEST=UNLOCK_CASTOUT
Identifying the Cast-Out Locks to Release
Initializing Elements in the List of Name Elements
Specifying a Process Identifier
Selecting a Buffering Method
Processing an UNLOCK_CASTOUT Request that Ends Prematurely
Locating a Name Element
Restarting a Request
Receiving Answer Area Information
Changing the Directory Entry for the Data Item
Indicating to the System not to Change the Status of the Data Item
Marking the Data Item as Changed
When Another User Updates the Data Item
Releasing Cast-Out Locks: Summary
UNLOCK_CO_NAME: Releasing a Single Cast-Out Lock
IXLCACHE Functions for REQUEST=UNLOCK_CO_NAME
Identifying the Cast-Out Lock to Release
Initializing a Name Element
Specifying a Process Identifier
Selecting a Buffering Method
Receiving Answer Area Information
Changing the Directory Entry for the Data Item
Indicating to the System not to Change the Status of the Data Item
Marking the Data Item as Changed
When Another User Updates the Data Item
Releasing a Single Cast-Out Lock: Summary
DELETE_NAME: Deleting Data Items From a Cache Structure
IXLCACHE Functions for REQUEST=DELETE_NAME
Identifying Data Items to Delete
Example 1
Example 2
Example 3
Specifying the Type of Deletion
Using Name Classes in a Coupling Facility
Restarting Requests
Receiving Answer Area Information
Deleting Data Items: Summary
DELETE_NAMELIST: Deleting a List of Data Items
IXLCACHE Functions for REQUEST=DELETE_NAMELIST
Identifying Data Items to Delete
Selecting a Buffering Method
Specifying the Type of Deletion
Requesting Version Comparison
Handling Error Processing
Restarting a DELETE_NAMELIST Request that Ends Prematurely
Receiving Answer Area Information
Deleting a List of Data Items: Summary
CROSS_INVAL: Invalidating Other Users' Copies of Data Items
Timing and CROSS_INVAL Requests
IXLCACHE Functions for REQUEST=CROSS_INVAL
Identifying Data Items to Cross-Invalidate
Restarting a Request that Ends Prematurely
Receiving Answer Area Information
Cross-Invalidating a Data Item: Summary
CROSS_INVALLIST: Invalidating a List of Data Items
IXLCACHE Functions for REQUEST=CROSS_INVALLIST
Identifying the list of data items to be cross-invalidated
Selecting a Buffering Method
Handling Error Processing
Restarting a CROSS_INVALLIST Request that ends prematurely
Receiving answer area information
Cross-invalidating a list of data items: Summary
SET_RECLVCTR: Overriding or Restoring the Default Reclaim Algorithm
Defining the Reclaim Vector
IXLCACHE Functions for REQUEST=SET_RECLVCTR
Specifying the Storage Class
Specifying the Reclaim Vector
Example Scenarios
Scenario 1 - First Request
Scenario 2 - Second Request
Scenario 3 - Third Request
Scenario 4 - Fourth Request
Activating a Reclaim Vector
Deactivating a Reclaim Vector
Effect of Structure Alter on Reclaim Vectors
Receiving Answer Area Information
Overriding or Restoring the Default Reclaim Algorithm: Summary
PROCESS_REFLIST: Marking Data Items as Referenced
IXLCACHE Functions for REQUEST=PROCESS_REFLIST
Identifying Data Items to Mark as Referenced
Selecting the Buffering Method
Specifying the Storage Class
Receiving Answer Area Information
Marking a Data Item as Referenced: Summary
RESET_REFBIT: Marking Data Items as Unreferenced
IXLCACHE Functions for REQUEST=RESET_REFBIT
Identifying Data Items to Mark as Unreferenced
Restarting a Request that Ends Prematurely
Receiving Answer Area Information
Marking a Data Item as Unreferenced: Summary
READ_DIRINFO: Reading Cache Directory Entries
IXLCACHE Functions for REQUEST=READ_DIRINFO
Identifying the Directory Entries to Read
Selecting the Buffering Method
Format of Returned Directory Information
Reading All Directory Information
Reading a Subset of Directory Information
Restarting a REQUEST=READ_DIRINFO Request that Ends Prematurely
Reading Directory Entry Information: Summary
READ_COCLASS: Reading A Cast-Out Class
IXLCACHE Functions for REQUEST=READ_COCLASS
Specifying the Data Item
Specifying the Cast-Out Class
Selecting the Buffering Method
Format of Returned Cast-Out Class Data
Restarting a REQUEST=READ_COCLASS Request that Ends Prematurely
Selecting the restart algorithm type
Receiving Answer Area Information
Reading a Cast-Out Class: Summary
READ_COSTATS: Reading Cast-Out Class Statistics
IXLCACHE Functions for REQUEST=READ_COSTATS
Specifying the Cast-out Classes
Selecting a Buffering Method
Format of Returned Cast-out Statistics
The First Word
The Remainder of the Buffer
Restarting A REQUEST=READ_COSTATS Request that Ends Prematurely
Receiving Answer Area Information
Reading Cast-out Statistics: Summary
READ_STGSTATS: Reading Storage Class Statistics
IXLCACHE Functions for REQUEST=READ_STGSTATS
Specifying the Storage Class
Providing a Storage Area for Returned Statistics
Description of Returned Statistics
Receiving Answer Area Information
Reading Storage Class Statistics: Summary
Coding a Complete Exit for IXLCACHE
Information Passed to the Complete Exit
Environment
Input Specifications
Registers at Entry:
Return Specifications
Programming Considerations
Managing Cache Structure Utilization
Detecting When a Cache Structure Is Becoming Full
Responding When the Structure Is Getting Full
Rebuilding the Structure to Increase the Storage Capacity
Altering the Structure to Increase the Storage Capacity
Using List Services (IXLLIST)
List Structure Concepts
What is a List Structure?
List Structure Enhancements
How Is Data Maintained in a List Structure?
What Functions Does the List Structure Provide?
Referencing List Entries
Understanding List Entry Key Assignment
Available Options for Automatic List Entry Key Assignment
Specifying a List Entry by List Position
Specifying a List Entry by List Position and Key
Using the Entry Key in Multiple List Operations
Understanding the List Cursor
Initializing the List Cursor
Controlling How the List Cursor Is Updated
Using the List Cursor
Resetting the List Cursor to Zero
Specifying a List Entry by Entry ID
Specifying a Named List Entry by Entry Name
Understanding List Structure Monitoring
The List Notification Vector
Options for Detecting a List or Event Queue Transition
Understanding the Event Queue
Monitoring the Event Queue
Understanding Event Queue Controls
Understanding Event Monitor Controls
Understanding Sublist Monitoring
Reviewing Sublist and Event Queue Monitoring
Understanding List Entry Controls
Understanding List Controls
List Controls That Can Be Updated Using WRITE_LCONTROLS
List Controls That Cannot be Updated Using WRITE_LCONTROLS
List Controls That Can Be Updated Using READ, WRITE, MOVE, and DELETE
Understanding List Counts
Understanding the List Authority Value
Using the List Authority Value to Select Entries for Processing
Updating the List Authority Value
Understanding the User Exits
Understanding Synchronous and Asynchronous List Operations
Using the IXLFCOMP Macro with MODE=ASYNCTOKEN or MODE=SYNCTOKEN
Understanding the Serialized List Structure
Overview of Locking Functions
Conditional and Unconditional Lock Requests
Understanding Lock Contention and the Notify Exit
Contention Processing
The Notify Exit
Designing Protocols for Using the Serialized List Structure
Maintaining Information about the Lock Request
Identifying the Lock Owner
Distinguishing One Lock Request from Another
Managing Multiple, Asynchronous Lock Requests
Recovering Locks Held by Failed or Failing Connections
Recovering Persistent Locks
Reconnecting with Persistent Locks
Summary of Recovery Steps for Failed Connector to a Serialized List Structure
Understanding the List Entry Version Number
Setting the List Entry Version Number
Using the Version Number to Select List Entries for Processing
Using the Version Number to Serialize List Entry Operations
Selecting the Buffer Format
BUFFER and Its Associated Parameters
BUFLIST and Its Associated Parameters
Design Considerations for Choosing the Buffer Format
Design Considerations for Defining Buffer Storage Areas
Determining Buffer Storage Ownership
Using Real Versus Virtual Storage
Deciding Whether to Provide Page-Fixed Storage
Specifying the Buffer Storage Key
WRITE: Writing to a List Entry
Understanding the Write Operation
Specifying the Type of Write Operation
Specifying the Size of the Data Entry to Hold the Data
Specifying the List Entry Version Number on a WRITE Request
Specifying the List Authority Value on a WRITE Request
Requesting Automatic Key Assignment on a WRITE Request
Passing Data for a WRITE Request
Requesting a Lock Operation as Part of a WRITE Request
Updating an Existing List Entry
Creating a New List Entry
Creating a New Keyed List Entry in a CFLEVEL=3 or Higher Coupling Facility
Creating a List Entry With No Data
Receiving Answer Area Information from a WRITE Request
Determining if the Answer Area is Valid
READ, READ_MULT, READ_LIST: Reading List Entries
READ: Reading a Single List Entry
Specifying the List Entry Version Number on a READ Request
Specifying the List Authority Value on a READ Request
Requesting a Lock Operation as Part of a READ Request
Receiving Data from a READ Request
Obtaining the List Entry Information from the Output Areas
Receiving Answer Area Information from a READ Request
READ_LIST: Reading Multiple List Entries from a List
Specifying the Starting List Entry and the Processing Direction
Specifying the Types of List Entry Information to be Read
Specifying the List Entry Version Number on a READ_LIST Request
Specifying the List Authority Value on a READ_LIST Request
Requesting Entry Key Comparison on a READ_LIST Request
Requesting a Lock Operation as Part of a READ_LIST Request
Receiving Data from a READ_LIST Request
Handling an Incompletely Processed READ_LIST Request
The Effect of List Changes on Request Resumption
Receiving Answer Area Information from a READ_LIST Request
READ_MULT: Reading Multiple List Entries from One or More Lists
Specifying Selection Filters on a READ_MULT Request
Requesting a Lock Operation as Part of a READ_MULT Request
Receiving Data from a READ_MULT Request
Handling an Incompletely Processed READ_MULT Request
Receiving Answer Area Information from a READ_MULT Request
MOVE: Moving a List Entry
Understanding the MOVE Operations
Specifying the List Entry to be Moved
List Cursor Placement on a MOVE Request
Specifying the Target List and List Position
For a list structure with entry names
For a list structure with entry keys
For a list structure with neither entry names nor entry keys
Receiving or Passing Data on a MOVE Request
Specifying the List Entry Version Number on a MOVE Request
Specifying the List Authority Value on a MOVE Request
Requesting Automatic Key Assignment on a MOVE Request
Requesting a Lock Operation as Part of a Move Request
Moving a Keyed List Entry in a CFLEVEL=3 or Higher Coupling Facility
Moving a List Entry Without Performing a Read or Write Operation
Performing a Read Operation as Part of a Move Request
Performing a Write Operation as part of a MOVE Request
Creating a New List Entry as Part of a MOVE Request
Receiving Answer Area Information from a MOVE Request
DELETE, DELETE_MULT, DELETE_ENTRYLIST: Deleting List Entries
DELETE: Deleting a Single List Entry
Requesting a Lock Operation as Part of a DELETE Request
Specifying the List Entry to be Deleted
Specifying the List Entry Version Number on a DELETE Request
Specifying the List Authority Value on a DELETE Request
Deleting a Keyed List Entry in a CFLEVEL=3 or Higher Coupling Facility
Receiving Data on a DELETE Request
Receiving Answer Area Information from a DELETE Request
DELETE_MULT: Deleting Multiple List Entries
Requesting a Lock Operation as Part of a DELETE_MULT Request
Handling an Incompletely Processed DELETE_MULT Request
Receiving Answer Area Information from a DELETE_MULT Request
DELETE_ENTRYLIST: Deleting a List of Entries
Passing the List of Entries to be Deleted
Requesting a Lock Operation as Part of a DELETE_ENTRYLIST Reques
Handling an Incompletely Processed DELETE_ENTRYLIST Request
Receiving Answer Area Information from a DELETE_ENTRYLIST Request
READ_LCONTROLS: Reading List Controls
Obtaining List Monitoring Information
Receiving Answer Area Information from a READ_LCONTROLS Request
WRITE_LCONTROLS: Writing List Controls
Changing the List Limit
Effect of Structure Alter on the List Limit
Receiving Answer Area Information from a WRITE_LCONTROLS Request
LOCK: Performing a Lock Operation
Selecting the Lock Operation
Handling an Incompletely Processed LOCK Request that Specifies LOCKOPER=READNEXT
Receiving Answer Area Information from a LOCK Request
MONITOR_LIST: Monitoring List Transitions
The List Notification Vector
Options for Detecting a List Transition
Steps to Set Up List Transition Monitoring
Indicating Your Interest in List Transition Monitoring
Starting Transition Monitoring of a List
Stopping Transition Monitoring of a List
Design Considerations for Using the List Transition Exit
Timing Considerations
Best Circumstances for Using List Monitoring
Receiving Answer Area Information from a MONITOR_LIST Request
MONITOR_EVENTQ: Monitoring an Event Queue
Steps to Set Up Event Queue Transition Monitoring
Indicating Your Interest in Event Queue Transition Monitoring
Starting Transition Monitoring of an Event Queue
Stopping Transition Monitoring of an Event Queue
Receiving Answer Area Information from a MONITOR_EVENTQ Request
MONITOR_SUBLIST, MONITOR_SUBLISTS: Monitoring Sublists
Understanding the Event Queue
Indicating Your Interest in Sublist Transition Monitoring
Specifying User Notification Controls
MONITOR_SUBLIST: Monitoring a Single Sublist
Starting Transition Monitoring of a Sublist
Stopping Transition Monitoring of a Sublist
Scenario for Monitoring a Sublist
Receiving Answer Area Information from a MONITOR_SUBLIST Request
MONITOR_SUBLISTS: Monitoring Multiple Sublists
Identifying the Sublists to be Monitored
Passing Buffered Data on a MONITOR_SUBLISTS Request
Using the Monitored Object State Vector
Handling an Incompletely Processed MONITOR_SUBLISTS Request
Receiving Answer Area Information from a MONITOR_SUBLISTS Request
READ_EMCONTROLS: Reading Event Monitor Controls
Receiving Answer Area Information from a READ_EMCONTROLS Request
READ_EQCONTROLS: Reading Event Queue Controls
Obtaining Event Queue Monitoring Information
Receiving Answer Area Information from a READ_EQCONTROLS Request
DEQ_EVENTQ: Retrieving Events from the Event Queue
Handling an Incompletely Processed DEQ_EVENTQ Request
Receiving Answer Area Information from a DEQ_EVENTQ Request
Coding a Complete Exit
Information Passed to the Complete Exit
Environment
Input Specifications
Registers at Entry
Return Specifications
Programming Considerations
Circumstances a User Exit Should Be Prepared to Handle
Coding a Notify Exit
Information Passed to the Notify Exit
Environment
Input Specifications
Registers at Entry
Return Specifications
Programming Considerations
Coding a List Transition Exit
Information Passed to the List Transition Exit
Environment
Input Specifications
Registers at Entry
Return Specifications
Programming Considerations
Managing List Structure Utilization
Detecting When a List Structure Is Becoming Full
Responding When the Structure is Getting Full
Rebuilding the Structure to Increase the Storage Capacity
Altering the Structure to Increase the Storage Capacity
Enhancements to Sublist Monitoring
Using List Services (IXLLSTE, IXLLSTM, IXLLSTC)
Additional List Services Provided at OS/390 Release 9 and Higher
Understanding Program-Specified Entry Identifiers
Enhancement to List Services Entry Key and Secondary Key Comparison
Enhancements to List Monitoring
Understanding Secondary Keys
Using the New List Services Request Types
Specifying 64-bit buffers
Comparing IXLLSTC, IXLLSTE, and IXLLSTM with IXLLIST
Locating a List Entry
Specifying a Range of Values
Specifying Entry Keys or Secondary Keys
Identifying Individual List Entries for IXLLSTM Requests
IXLLSTE: List Structure Single Entry Services
Selecting an Entry for Processing by IXLLSTE
Requesting a Lock Operation as Part of an IXLLSTE Request
Requesting List Authority Checking
Requesting List Number Checking
Requesting Version Number Checking
Requesting Entry Key Comparison Checking
Requesting Secondary Key Comparison Checking
Receiving Answer Area Information
Creating a List Entry
Requesting Comparison Criteria when Creating a List Entry
Reading a List Entry
Requesting Comparison Criteria when Reading a List Entry
Writing a List Entry
Moving a List Entry
Requesting Comparison Criteria when Moving a List Entry
Specifying the List Entry to Be Moved
Specifying the Target List and List Position
Changing the List Entry Key
Creating a New List Entry with an IXLLSTE Move Request
Specifying Where to Place the New List Entry
Identifying the New List Entry
Deleting a List Entry
IXLLSTM: List Structure Multiple Entry Services
Selecting Entries for Processing by IXLLSTM
Requesting a Lock Operation as Part of an IXLLSTM Request
Requesting List Authority Checking
Requesting List Number Checking
Requesting Version Number Checking
Requesting Entry Key Comparison Checking
Requesting Secondary Key Comparison Checking
Receiving Answer Area Information
Restarting IXLLSTM Requests
Reading List Entries from a List
Deleting List Entries from a List
Reading List Entries from Multiple Lists
Request Comparison Checking on a READ_MULT Request
Handling an Incompletely Processed READ_MULT Request
Deleting List Entries from Multiple Lists
Request Comparison Checking on a DELETE_MULT Request
Handling an Incompletely Processed DELETE_MULT Request
Moving a List of List Entries
Request Comparison Checking on a MOVE_ENTRYLIST Request
Passing the List of Entries to be Moved
Updating Key Values When Moving List Entries
Handling an Incompletely Processed MOVE_ENTRYLIST
Deleting a List of List Entries
Request Comparison Checking on a DELETE_ENTRYLIST Request
Passing the List of Entries to be Deleted
IXLLSTC: List Structure Control Services
Understanding Threshold Counts
Using Threshold Counts when Monitoring List State Transitions
Setting the Threshold Counts for List Monitoring
Using Threshold Counts when Monitoring a Range of Key Values
Setting the Threshold Counts for Keyrange Monitoring
Handling an Incompletely Processed WRITE_LCONTROLS Request that Specifies KEYRANGESTATE=DEFINE
Reading Control Information for a List
Updating Control Information for a List
Monitoring a List
Monitoring a Sublist
Monitoring a Set of Sublists
Monitoring a List by Keyrange Values
Using the List Notification Vector
Starting and Stopping Keyrange Monitoring
Handling an Incompletely Processed MONITOR_KEYRANGE Request
Monitoring an Event Queue
Reading EMC Control Information
Reading Event Queue Control Information
Dequeuing Event Monitor Controls from an Event Queue
Performing Lock Operations
Reading Structure Counts for a List Structure
Using Lock Services (IXLLOCK)
Resource Concepts
What Is a Resource?
State of a Resource Request Queue
What Can You Do With the XES Lock Services?
Managing Contention
Defining a Protocol to Handle Contention
How is Contention Resolved?
What Can You Do in a Contention Exit?
Sample Locking Protocol — Definition
Sample Locking Protocol — Implementation
Informing a User of Request Completion
Using the IXLLOCK MODE Parameter
Lock Structure Concepts
The Lock Table
Identifying a Lock Table Entry
Assigning a Resource Name
Assigning a Hash Value
Mapping a Resource Name to a Lock Table Entry
Composite State of a Lock Table Entry
Understanding Contention
Creating an Efficient Locking Protocol
Analyzing Your Locking Protocol
Record Data Entries
Associating Record Data Entries with Connected Users
Capacity Planning for Record Data Entries
Size Considerations for a Lock Structure
Lock Table Size
Storage Required for Record Data Entries
Effect of Structure Alter on a Lock Structure
Recovery Considerations
Designing for Recovery
Defining the Connections
Specifying Recovery Information
XES Cleanup Processing
Sample Recovery Protocol
Sample Recovery Protocol - An Alternative
Requesting Lock Services
Requesting Ownership of a Resource (REQUEST=OBTAIN)
Determining the Completion of an OBTAIN Request
Return and Reason Codes
Changing Ownership Attributes (REQUEST=ALTER)
Determining the Completion of an ALTER Request
Return and Reason Codes
Releasing Ownership of a Resource (REQUEST=RELEASE)
Determining the Completion of a RELEASE Request
Return and Reason Codes
Processing Multiple Resource Requests (REQUEST=PROCESSMULT)
Processing a Lock Request Block
Determining the Completion of a PROCESSMULT Request
Examining PROCESSMULT Return and Reason Codes
Examining Lock Request Block Return and Reason Codes
Using Exits for Coupling Facility Lock Services
General Requirements
Environment
Input Specifications
Return Specifications
Serialization
Ordering of IXLLOCK Exit Routines
Contention/Notify Exit Sequencing
Complete/Notify Exit Sequencing
Exit Recovery
Programming Considerations
Performance Implications
Coding a Complete Exit
Information Passed to the Complete Exit
Return and Reason Codes
Programming Considerations
Coding a Contention Exit
Assigning Resource Contention Management
Passing Information to the Contention Exit
Contention Exit Processing
XES/Contention Exit Communication
Continue Contention Management
Stop Contention Management
Call Contention Exit Again
Defer Contention Management during Rebuild
Summary of XES Contention Exit Processing
Return and Reason Codes
Programming Considerations
Coding a Notify Exit
XES/Notify Exit Communication
Notify Exit Routine Processing
Return and Reason Codes
Programming Considerations
Using the Synchronous Update Service (IXLSYNCH)
Notify Exit/IXLSYNCH Communication
Addressing the Notify Exit Parameter List
Processing the Modifications
Informing a User of Request Completion
Using the IXLSYNCH MODEVAL Parameter
Using the Lock Cleanup and Recovery Service (IXLRT)
Identifying the User
Providing Areas for Returned Data
Specifying the Level of Information
Identifying the Record Data
Assigning a Record Data Type to the Record Data
What You Can Request with IXLRT
Handling an Incompletely Processed IXLRT Request
Supplementary List, Lock, and Cache Services
Using the IXLFCOMP Macro
Issuing IXLFCOMP During Recovery Processing
Purging a Coupling Facility Operation
Handling Operations in Progress
Handling Operations Yet to be Processed
Timing Considerations
Using the IXLVECTR Macro
List Notification Vector
Changing the Number of Entries in a List Notification Vector
Testing Whether a List or Event Queue Is Empty
Testing Whether a Range of Lists is Empty
Local Cache Vector
Changing the Number of Entries in a Local Cache Vector
Checking the Validity of Data Items in a Local Cache Buffer
Using the TESTLOCALCACHE and LTVECENTRIES Requests with a Serialization Protocol
Using Note Pad Services (IXCNOTE)
Note pad concepts and terminology
Use of the term connection
Designing your application to use an XCF Note Pad
What is a note
Note name
Note instance number
Note tags
Note content
Note connection identifier
Note persistence
What is an XCF Note Pad
Note pad name
Choosing a note pad name
Note pad names and structure selection
Note pad names and SAF authorization
Note pad description
Note pad information
Note limit
Duplexing preference
Note pad protocols
Multi-write access
Instance number comparison
Note tag assignment
Tracking of maximum tag values
Timestamp when created
What is a connection
Connection token
Connection identifier
Connection description
Connection information
Access scope
Connection scope
Usage classification
Connector usage
Server usage
Client usage
Termination scope
Using the IXCNOTE macro
Answer area
System Authorization Facility (SAF) requirements
Use of a connection token
Quiescing conditions
Constrained conditions
Full considerations
Constraint considerations
Pending deletes
Timeout conditions
Status unknown conditions
Considerations for note pad requests
Considerations for connection requests
Considerations for single note requests
Considerations for multi-note requests
XCF component failures
Note pad requests
Create note pad
Query note pad
Delete note pad
Designating a unique note pad instance
Conditional delete
Unconditional delete
Connection requests
Create connection
Using the CONNECTION keyword
Delete connection
Pause connection
Resume paused connection
Single note requests
Overview
Using the CONNECTION keyword
Answer area
Note content with the NOBUFFER keyword
Note content with the BUFFER and BUFLEN keywords
Note tags
Note instance numbers
Note persistence
Create note
Replace note
Write note
Read note
Delete note
Multi-note requests
Overview
Using the CONNECTION keyword
Answer area
Selection criteria
Multi-note selection criteria
Concurrent request issues
Read notes
Premature completion
Resume token
Buffer area and note size
Failure conditions and partial results
Delete notes
Deferred delete
MAXTAG and note selection
MAXTAG with lifetime tracking of user assigned note tags
Failure conditions and partial results
Note pad related limits
Buffer size and single note requests
Buffer size and multi-note requests
Coupling Facility Accounting and Measuring Services
Using IXLMG
Specifying the Information Level
Types of Information Available
Defining an Output Area
Programming Considerations
Specifying the Information To Be Returned by IXLMG
Coupling Facility Information
Coupling Facility Structure Information
Dumping Services for Coupling Facility Structures
Using the IHABLDP Macro
Using the IXLZSTR Macro
Requesting Structure Information
Receiving Information Returned by the IXLZSTR Macro
Using Component Data in the Dump Data Set
Associating Macros with the Data Types
Documenting your Coupling Facility Requirements
Specifying the Coupling Facility Structure Requirements
Naming the Structure
Determining the Structure Size
Providing an Exclusion List
Understanding the Persistence Attribute
Specifying the Rebuild and/or Alter Attribute
Providing Connectivity Requirements
Specifying the Coupling Facility Requirements
Summarizing Your Requirements