OA60650: NEW FUNCTION - CFLEVEL 25 Exploitation Support

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• NEW FUNCTION - CFLEVEL 25 Exploitation Support
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * Installations exploiting coupling facility (CF) lock or      *
  * cache structures in a parallel sysplex at z/OS V2R3          *
  * (HBB77B0) and above with a z16 model 3931 CFLEVEL 25 in the  *
  * sysplex configuration.                                       *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * Lock structure applications need a way to obtain additional  *
  * locks with record data for transactional recovery and back   *
  * out processing when encountering a lock structure full       *
  * condition.                                                   *
  *                                                              *
  * Cache structure applications need a way to know how long     *
  * data and directory entries reside in a cache structure       *
  * before they are reclaimed to measure CF cache structure      *
  * effectiveness and provide improved recommendations for       *
  * optimizing structure size or re-targeting work to other      *
  * cache structures.                                            *
  *                                                              *
  * SYSPLEXDS                                                    *
  * E3931/K                                                      *
  * D/T3931                                                      *
  ****************************************************************
  * RECOMMENDATION:                                              *
  * Install the applicable PTF on each system in the sysplex. A  *
  * rolling IPL is sufficient to activate the fix.               *
  ****************************************************************
  Lock structure applications that need to obtain additional locks
  with record data to perform back out recovery when incurring a
  structure full condition can not obtain the necessary lock
  structure resources to complete recovery without manual
  installation intervention which results in availability
  disruptions. Lock structure users would like a way to reserve a
  percentage of lock structure record data entries that would not
  be generally available for use unless explicitly requested.
  
  Data management applications need cache structure data and
  directory residency statistics to measure how long data and
  directory entries reside in a cache structure before they are
  reclaimed. This information can help clients improve structure
  sizing estimates and apportioning as well as workload balancing
  between cache structures.
  

Problem conclusion

Temporary fix

Comments

• OA60650 provides new functionality for cache and lock structures
  residing in a CFLEVEL 25 CF.
  
  Percent Entry Reserve for lock structures
  -----------------------------------------
  
  To allow exploiters of lock structures the capability to specify
  a percentage of structure record data entries to be reserved
  from general use, a CF structure program modifiable control can
  be set via the IXLCONN service. By setting aside a percentage of
  record data entries, an application can better manage the
  availability of record data entries. The PCTENTRYRSV keyword can
  be used to specify the percentage of the total number of record
  data entries that must remain free after a command that creates
  a record data entry completes and after a structure alter
  completes.  XES will take the composite value specified by all
  connectors on the IXLCONN service and use the highest percentage
  value specified to set the percent entry reserved threshold for
  the structure.
  
  Keyword ALLOWUSERSV on the XES IXLLOCK and IXLRT services and
  via a connector's NOTIFY exit using the notify exit parameter
  list (IXLYNEPL) can be used to allow a request that attempts to
  create a record data entry to proceed if the resulting
  percentage of free (unused) entries at the completion of the
  request would be less than the established percent entry
  reserved threshold (if any) for the structure.
  
  
  
  Residency Time Metrics for cache structures
  -------------------------------------------
  
  XES services can be used to gather new CF-related cache
  structure information available in a CFLEVEL 25 CF.
  
  A CF at CFLEVEL 25 will store a timestamp in each cache entry
  when the entry becomes valid and when it first contains data.
  When a data-area or directory-entry gets reclaimed out of
  existence, the CF will take another timestamp and calculate the
  elapsed residency time. The elapsed residency time will
  contribute to the data-area or directory-entry residency time
  statistic, a moving weighted average that will approximate the
  residency time in microseconds averaged on a per-storage-class
  basis. An application can use the XES IXLMG and IXLCACHE
  services to gather the elapsed residency times for directory and
  data-area entries.
  
  For more information on how to retrieve data-area and directory
  entry residency time metrics and reserve lock structure record
  data entries, see z/OS MVS Sysplex Services Guide (SA23-1400)
  and z/OS MVS Sysplex Services Reference (SA38-0658).
  
  
  Documentation updates
  =====================
  
  Complete publication updates are available at
  http://public.dhe.ibm.com/s390/zos/xes-xcf/OA60650.pdf
  
  Summary of updates:
  
  z/OS: MVS Programming: Sysplex Services Guide  SA23-1400
  --------------------------------------------------------
  
  The following topics have been updated:
  
  - Using the IXCQUERY Macro
  - Connecting to a lock structure
  - Using the IXLCONN macro for rebuilds
  - Record data entries
  - Specifying Recovery Information
  - Requesting Ownership of a Resource (REQUEST=OBTAIN)
  - Changing Ownership Attributes (REQUEST=ALTER)
  - Using the Synchronous Update Service (IXLSYNCH)
  - Using the Lock Cleanup and Recovery Service
  
  
  z/OS: MVS Programming: Sysplex Services Reference  SA38-0658
  ------------------------------------------------------------
  
  The following chapters have been updated:
  
  - IXLCONN - Connect to a coupling facility structure
  - IXLLOCK - IXLLOCK Services
  - IXLRT - Lock structure record data processing
  - IXLSYNCH - Synchronous update to a lock structure
  
  
  z/OS MVS Data Areas Volume 3 (ITK-SCE) GA32-0937
  ---------------------------------------------
  
  The following data areas have been updated:
  
  - IXCYQUAA
  - IXLYAMDA
  - IXLYCON
  - IXLYCSCS
  - IXLYDSCC
  - IXLYNEPL
  
  
  z/OS MVS System Messages Volume 10 (IXC-IZP)  SA38-0677
  -----------------------------------------------------
  
  The following message has been updated:
  
  - IXC360I
  - IXC585E
  
  
  z/OS MVS Setting up a Sysplex (SA23-1399)
  -----------------------------------------
  
  The following topics have been updated:
  
  - Monitoring structure utilization
  - Structure full avoidance
  - CFLEVEL and operating system level coexistence
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UJ08374 UJ08375 UJ08376 UJ08377 UJ08378 UJ08379

Modules/Macros

• IXCL2BAP IXLRT    IXCM2MST IXLC1CON IXCL2ASR IXLR1CAC IXCL2SCC
  IXCYQUAA IXLYCSCS IXLCONN  IXLF1STC IXLR1ALR IXCL2ATC IXLR1LST
  IXCL2ATH IXLYCON  IXLR1GRT IXLR2PLA IHADWHDR IXCM2MS3 IXCL2MON
  IXLYDSCC IXLYNEPL IXCF1TX2 IXLR1LKR IXCF1TF6 IXCL2ACE IXLYAMDA
  IXLLOCK  IXCL2SCL IXLLSTE  IXLR1RT  IXLSYNCH IXCL2CST IXLM1MS2
  IXCL2QRY IXCI2PH1 IXLR1SYN IXCL2AAT IXCO1DC3 IXLA1MG  IXCXCFEN
  IXCXCFJP
  

Fix information

• Fixed component name

  CROSS SYS.EXT.S

• Fixed component ID

  5752SCIXL

Applicable component levels

• R7BJ PSY UJ08377

     UP22/05/31 P F205  

• R7DJ PSY UJ08379

     UP22/05/31 P F205  

• R7CJ PSY UJ08378

     UP22/05/31 P F205  

• R7D0 PSY UJ08376

     UP22/05/31 P F205  

• R7C0 PSY UJ08375

     UP22/05/31 P F205  

• R7B0 PSY UJ08374

     UP22/05/31 P F205  

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.